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1 一 简介 


Lua 是 一 门 扩 展 式 程序 设计 语言 ， 被 设计 成 支持 通用 过 程式 编程 ， 并 有 相关 数据 描述 设施 。 
同时 对 面向 对 象 编程 、 辑 数 式 编程 和 数据 驱动 式 编程 也 提供 了 良好 的 支持 。 它 作 为 一 个 强 
大 、 轻 量 的 做 入 式 脚本 语言 ， 可 供 任何 需要 的 程序 使 用 。 Lua 由 clean C (标准 C 和 C++ 间 
共通 的 子 集 ) 实现 成 一 个 库 。 


作为 一 门 扩 展 式 语言 ，Lua 没有 "main" 程序 的 概念 : 它 只 能 伐 入 一 个 宿主 程序 中 工作 ， 该 
宿主 程序 被 称 为 被 戏 入 程序 或 者 简称 宿主 。 宿主 程序 可 以 调用 函数 执行 一 小 段 Lua 代码 ， 
可 以 读 写 Lua 变量 ， 可 以 注册 C 本 数 让 Lua 代码 调用 。 依靠 C 画 数 ，Lua 可 以 共享 相同 的 
语法 框架 来 定制 编程 语言 ， 从 而 适用 不 同 的 领域 。 Lua 的 官方 发 布 版 包含 一 个 叫做 lua 的 
宿主 程序 示例 ， 它 是 一 个 利用 Lua 库 实 现 的 完整 独立 的 Lua 解释 器 ， 可 用 于 交互 式 应 用 或 批 
义理 。 


Lua 是 一 个 自由 软件 ， 其 使 用 许可 证 决定 了 它 的 使 用 过 程 无 需 任何 担保 。 本 手册 所 描述 的 实 
现 可 以 在 Lua 的 官方 网 站 www.1lua.org 找到 。 


与 其 它 的 许多 参考 手册 一 样 ， 这 份 文档 有 些 地 方 比较 枯燥 。 关于 Lua 背后 的 设计 思想 ， 可 以 
看 看 Lua 网 站 上 提供 的 技术 论文 。 至 于 用 Lua 编程 的 细节 介绍 ， 请 参阅 Roberto 的 
书 ，Programming in Lua。 


2 - 基本 概念 


本 章 描述 了 语言 的 基本 概念 。 


2.1 一 值 与 类 型 


Lua 是 一 门 动态 类 型 语言 。 这 意味 着 变量 没有 类 型 ; 只 有 值 才 有 类 型 。 语言 中 不 设 类 型 定 
义 。 所 有 的 值 携 带 自己 的 类 型 。 


Lua 中 所 有 的 值 都 是 一 等 公民 。 这 意味 着 所 有 的 值 均 可 保存 在 变量 中 、 当 作 参数 传递 给 其 它 
男 数 、 以 及 作为 返回 值 。 


Lua 中 有 八 种 基本 类 型 : ni boolean、number、string、function、userdata、 thread 和 
table。 Nil 是 值 nil 的 类 型 ， 其 主要 特征 就 是 和 其 它 值 区 别 开 ; 通常 用 来 表示 一 个 有 意义 的 值 
不 存在 时 的 状态 。 Boolean 是 false 与 true 两 个 值 的 类 型 。 nil 和 false 都 会 导致 条 件 判断 
为 假 ; 而 其 它 任何 值 都 表示 为 真 。 Number 代表 了 整数 和 实数 〈 浮 点 数 ) 。 String 表示 一 个 
不 可 变 的 字 节 序列 。 Lua 对 8 位 是 友好 的 : 字符 串 可 以 容纳 任意 8 位 值 ， 其 中 包含 零 

(\@ ') 。 Lua 的 字符 串 与 编码 无 关 ; 它 不 关心 字符 串 中 具体 内 容 。 


number 类 型 有 两 种 内 部 表现 方式 ， 整数 和 浮 点 数 。 对 于 何 时 使 用 哪 种 内 部 形式 ，Lua 有 明 
确 的 规则 ， 但 它 也 按 需 (参见 $S3.4.3) 作 自 动 转换 。 因此 ， 程 序 员 多 数 情况 下 可 以 选择 忽略 
整数 与 浮 点 数 之 间 的 差异 或 者 假设 完全 控制 每 个 数字 的 内 部 表现 方式 。 标准 Lua 使 用 64 位 
整数 和 双 精 度 (64 位 ) 浮 点 数 ， 但 你 也 可 以 把 Lua 编译 成 使 用 32 位 整数 和 单 精度 (32 

位 ) 浮 点 数 。 以 32 位 表示 数字 对 小 型 机 器 以 及 内 入 式 系 统 特别 合适 。 (参见 luaconf.h 文 
件 中 的 宏 LUA 32BITS 。) 


Lua 可 以 调用 (以 及 操作 ) 用 Lua 或 C (参见 S3.4.10) 编写 的 函数 。 这 两 种 画 数 有 统一 类 
型 function。 


userdata 类 型 允许 将 C 中 的 数据 保存 在 Lua 变量 中 。 用 户 数据 类 型 的 值 是 一 个 内 存 块 ， 有 
两 种 用 户 数据 : 完全 用 户 数据 ， 指 一 块 由 Lua 管理 的 内 存 对 应 的 对 象 ; 轻 量 用 户 数据 ， 则 
指 一 个 简单 的 C 指针 。 用 户 数据 在 Lua WE 
作 。 通过 使 用 元 表 ， 程 序 员 可 以 给 完全 用 户 数据 定义 一 系列 的 操作 (参见 $2.4) 。 你 只 能 
通过 C API 而 无 法 在 Lua 代码 中 创建 或 者 修改 用 户 数据 的 值 ， 这 保证 了 数据 仅 被 宿主 程序 所 
控制 。 


thread 类 型 表示 了 一 个 独立 的 执行 序列 ， 被 用 于 实现 协 程 (参见 $2.6) 。 Lua 的 线程 与 操作 
系统 的 线程 毫 无 关系 。 Lua 为 所 有 的 系统 ， 包 括 那些 不 支持 原生 线程 的 系统 ， 提 供 了 协 程 支 
持 。 


table 是 一 个 关联 数组 ， 也 就 是 说 ， 这 个 数组 不 仅仅 以 数字 做 索引 ， 除 了 nil 和 NaN 之 外 的 
所 有 Lua 值 都 可 以 做 索引 。 (Nota Number 是 一 个 特殊 的 数字 ， 它 用 于 表示 未 定义 或 表示 
不 了 的 运算 结果 ， 比 如 6/6 。) 表 可 以 是 异 构 的 ; 也 就 是 说 ， 表 内 可 以 包含 任何 类 型 的 值 
( nil 除外 ) 。 任何 键 的 值 若 为 nil 就 不 会 被 记 人 表 结 构 内 部 。 换言之 ， 对 于 表 内 不 存在 的 
键 ， 都 对 应 着 值 nil 。 


表 是 Lua 中 唯一 的 数据 结构 ， 它 可 被 用 于 表示 普通 数组 、 序 列 、 符 号 表 、 集 合 、 记 录 、 图 、 
树 等 等 。 对 于 记录 ，Lua 使 用 域名 作为 索引 。 语言 提供 了 a.name 这 样 的 语法 糖 来 替代 
a["name"] 这 种 写法 以 方便 记录 这 种 结构 的 使 用 。 在 Lua 中 有 多 种 便利 的 方式 创建 表 (参见 
§3.4.9) 。 


我 们 使 用 序列 这 个 术语 来 表示 一 个 用 {1..n} 的 正 整数 集 做 索引 的 表 。 这 里 的 非 负 整 数 n 被 称 
为 该 序列 的 长 度 (参见 83.4.7) 。 


和 索引 一 样 ， 表 中 每 个 域 的 值 也 可 以 是 任何 类 型 。 需要 特别 指出 的 是 : 既然 画 数 是 一 等 公 
民 ， 那 么 表 的 域 也 可 以 是 函数 。 这 样 ， 表 就 可 以 携带 方法 了 。 (参见 §3.4.11) 。 


索引 一 张 表 的 原则 遵循 语言 中 的 直接 比较 规则 。 当 且 仅 当 i 与 j 直接 比较 相等 时 ( 即 不 
通过 元 方法 的 比较 ) ， 表达 式 a[i] 与 a[j] 表示 了 表 中 相同 的 元 素 。 特别 指出 : 一 个 可 
以 完全 表示 为 整数 的 浮 点 数 和 对 应 的 整数 相等 (例如 : 1.6 == 1 ) 。 为 了 消除 歧义 ， 当 一 
个 可 以 完全 表示 为 整数 的 浮 点 数 做 为 键 值 时 ， 都 会 被 转换 为 对 应 的 整数 储存 。 例如 ， 当 你 写 
a[2.0] = true 时 ， 实际 被 插入 表 中 的 键 是 整数 2 。 ( 另 一 方面 ，2 与 " 2 " 是 两 个 不 同 的 
Lua 值 ， 故而 它们 可 以 是 同一 张 表 中 的 不 同 项 。) 


表 、 画 数 、 线 程 、 以 及 完全 用 户 数据 在 Lua 中 被 称 为 对 象 : 变量 并 不 真 的 持 有 它们 的 值 ， 
而 仅 保存 了 对 这 些 对 象 的 引用 。 赋值 、 参 数 传递 、 画 数 返 回 ， 都 是 针对 引用 而 不 是 针对 值 的 
操作 ， 这 些 操作 均 不 会 做 任何 形式 的 隐 式 拷贝 。 


库 豆 数 type 用 于 以 字符 串 形 式 返 回 给 定 值 的 类 型 。 (参见 §6.1) o 


2.2 -- 环境 与 全 局 环境 


后 面 在 $3.2 以 及 §3.3.3 会 讨论 ， 引用 一 个 叫 var 的 自由 名 字 ( 指 在 任何 层级 都 未 被 声明 的 
名 字 ) 在 句法 上 都 被 翻译 为 _ENvV.var 。 此 外 ， 每 个 被 编译 的 Lua 代码 块 都 会 有 一 个 外 部 的 
局 部 变量 趾 _ENv (参见 83.3.2) ， 因此 ， _ENv 这 个 名 字 永 远 都 不 会 成 为 一 个 代码 块 中 的 
自由 名 字 。 


在 转译 那些 自由 名 字 时 ， _ENv 是 否 是 那个 外 部 的 局 部 变量 无 所 谓 。 _ENv 和 其 它 你 可 以 使 
用 的 变量 名 没有 区 别 。 这 里 特别 指出 ， 你 可 以 定义 一 个 新 变量 或 指定 一 个 参数 叫 这 个 名 字 。 
当 编 译 器 在 转译 自由 名 字 时 所 用 到 的 _ENv ， 指 的 是 你 的 程序 在 那个 点 上 可 见 的 那个 名 为 
_ENV 的 变量 。 (Lua 的 可 见 性 规则 参见 §3.5) 


被 _ENv 用 于 值 的 那 张 表 被 称 为 环境 。 


Lua 保有 一 个 被 称 为 全 局 环境 特别 环境 。 它 被 保存 在 C 注册 表 (参见 $4.5) 的 一 个 特别 索 
引 下 。 在 Lua 中 ， 全 局 变量 6 被 初始 化 为 这 个 值 。 〈 _6 不 被 内 部 任何 地 方 使 用 。) 


当 Lua 加 载 一 个 代码 块 ， _ENv 这 个 上 值 的 默认 值 就 是 这 个 全 局 环境 (参见 load ) 。 
此 ， 在 默认 情况 下 ，Lua 代码 中 提 及 的 自由 名 字 都 指 的 全 局 环境 中 的 相关 项 〈 因 此 ， 它 们 也 
被 称 为 全 局 变量 ) 。 此 外 ， 所 有 的 标准 库 都 被 加 载 入 全 局 环境 ， 一 些 函 数 也 针对 这 个 环境 做 
操作 。 你 可 以 用 load (或 loadfile ) 加 载 代 码 块 ， 并 赋予 它们 不 同 的 环境 。 (在 C 里 ， 
当 你 加 载 一 个 代码 块 后 ， 可 以 通过 改变 它 的 第 一 个 上 值 来 改变 它 的 环境 。) 


2.3 一 错误 处 理 


由 于 Lua 是 一 门 柑 入 式 扩 展 语言 ， 其 所 有 行为 均 源 于 宿主 程序 中 C 代码 对 某 个 Lua 库 画 数 的 
调用 。 (单独 使 用 Lua 时 ， lua 程序 就 是 宿主 程序 。) 所 以 ， 在 编译 或 运行 Lua 代码 块 的 
过 程 中 ， 无 论 何 时 发 生 错误 ， 控制 权 都 返回 给 宿主 ， 由 宿主 负责 采取 恰当 的 措施 (比如 打印 
车 误 消息 ) oo 


可 以 在 Lua 代码 中 调用 error 辑 数 来 显 式 地 抛 出 一 个 错误 。 如 果 你 需要 在 Lua 中 捕获 这 些 
蓝 误 ， 可 以 使 用 pcall 或 xpcall 在 保护 模式 下 调用 一 个 画 数 。 


论 何 时 出 现 错误 ， 都 会 抛 出 一 个 携带 错误 信息 的 错误 对 象 (错误 消息 ) 。 Lua 本 身 只 会 关 
ie 吴 对 象 ， 但 你 的 程序 可 以 为 错误 生成 任何 类 型 的 错误 对 象 ， 这 就 看 
你 的 Lua 程序 或 宿主 程序 如 何 义理 这 些 错误 对 象 。 


使 用 xpcall 或 lua_pcall 时 ， 你 应 该 提供 一 个 消息 义理 函数 用 于 错误 抛 出 时 调用 。 该 函 
数 需 接 收 原 始 的 错误 消息 ， 并 返回 一 个 新 的 错误 消息 。 它 在 错误 发 生 后 栈 尚未 展开 时 调用 ， 
因此 可 以 利用 栈 来 收集 更 多 的 信息 ， 比如 通过 探知 栈 来 创建 一 组 栈 回 溯 信 息 。 同时 ， 该 处 理 
函数 也 久 于 保护 模式 下 ， 所 以 该 画 数 内 发 生 的 错误 会 再 次 触发 它 (递归 ) 。 如 果 递 妥 太 深 ， 
Lua 会 终止 调用 并 返回 一 个 合适 的 消息 。 


2.4 -- 元 表 及 元 方法 


Lua 中 的 每 个 值 都 可 以 有 一 个 元 表 。 这 个 元 表 就 是 一 个 普通 的 Lua 表 ， 它 用 于 定义 原始 值 
在 特定 操作 下 的 行为 。 如 果 你 想 改变 一 个 值 在 特定 操作 下 的 行为 ， 你 可 以 在 它 的 元 表 中 设置 
对 应 域 。 例如 ， 当 你 对 非 数 字 值 做 加 操作 时 ， Lua 会 检查 该 值 的 元 表 中 的 " " 域 下 的 画 
数 。 如 果 能 找到 ，Lua 则 调用 这 个 辑 数 来 完成 加 这 个 操作 。 


元 表 中 的 键 对 应 着 不 同 的 事件 名 ; 键 关 联 的 那些 值 被 称 为 元 方法 。 在 上 面 那 个 例子 中 引用 
的 事件 为 "add" ， 完成 加 操作 的 那个 函数 就 是 元 方法 。 


你 可 以 用 getmetatable 画 数 来 获 天 取 任 何 值 的 元 表 。 


使 用 setmetatable 来 蔡 换 一 张 表 的 元 表 。 在 Lua 中 ， 你 不 可 以 改变 表 以 外 其 它 类 型 的 值 的 
元 表 (除非 你 使 用 调试 库 (参见 86.10) ) ; 若 想 改变 这 些 非 表 类 型 的 值 的 元 表 ， 请 使 用 C 
APl。 


表 和 完全 用 户 数据 有 独立 的 元 表 (当然 ， 多 个 表 和 用 户 数据 可 以 共享 同一 个 元 表 ) 。 其 它 类 
型 的 值 按 类 型 共享 元 表 ; 也 就 是 说 所 有 的 数字 都 共享 同一 个 元 表 ， 所 有 的 字符 串 共 享 另 一 个 
元 表 等 等 。 默认 情况 下 ， 值 是 没有 元 表 的 ， 但 字符 串 库 在 初始 化 的 时 候 为 字符 串 类 型 设置 了 
元 表 (参见 §6.4) 。 


元 表决 定 了 一 个 对 象 在 数学 运算 、 位 运算 、 比 较 、 连 接 、 取 长 度 、 调 用 、 索 引 时 的 行为 。 元 
表 还 可 以 定义 一 个 函数 ， 当 表 对 象 或 用 户 数 据 对 象 在 垃圾 回收 (参见 82.5) 时 调用 它 。 


接 下 来 会 给 出 一 张 元 表 可 以 控制 的 事件 的 完整 列表 。 每 个 操作 都 用 对 应 的 事件 名 来 区 分 。 每 
个 事件 的 键 名 用 加 有 ' “前 级 的 字符 串 来 表示 ; 例如 "add" 操作 的 键 名 为 字符 串 

"”_add "。 注意 、Lua 从 元 表 中 直接 获取 元 方法 ; 访问 元 表 中 的 元 方法 永远 不 会 触发 另 一 次 
元 方法 。 下 面 的 代码 模拟 了 Lua 从 一 个 对 象 obj 中 获取 一 个 元 方法 的 过 程 : 


rawget(getmetatable(obj) or {}, " . event_name) 


对 于 一 元 操作 符 ( 取 负 、 求 长 度 、 位 反 ) ， 元 方法 调用 的 时 候 ， 第 二 个 参数 是 个 哑 元 ， 其 值 
等 于 第 一 个 参数 。 这 样 处 理 仅 仅 是 为 了 简化 Lua 的 内 部 实现 (这 样 处 理 可 以 让 所 有 的 操作 都 
和 二 元 操作 一 致 ) ， 这 个 行为 有 可 能 在 将 来 的 版 本 中 移 除 。 (使 用 这 个 额外 参数 的 行为 都 是 
不 确定 的 。) 


。 "add": + 操作 。 如 果 任 何不 是 数字 的 值 (包括 不 能 转换 为 数字 的 字符 串 ) 做 加 法 ， 
Lua 就 会 尝试 调用 元 方法 。 首先 、Lua 检查 第 一 个 操作 数 (即使 它 是 合法 的 ) ， 如 果 这 
个 操作 数 没 有 为 ”__add " 事件 定义 元 方法 ， Lua 就 会 接着 检查 第 二 个 操作 数 。 一 旦 Lua 
找到 了 元 方法 ， 它 将 把 两 个 操作 数 作为 参数 传人 元 方法 ， 元 方法 的 结果 (调整 为 单个 
值 ) 作为 这 个 操作 的 结果 。 如 果 找 不 到 元 方法 ， 将 抛 出 一 个 错误 。 

。 "sub": - 操作 。 行为 和 "add" 操作 类 似 。 

。 "mul": * 操作 。 行为 和 "add" 操作 类 似 。 

。 "div": / 操作 。 行为 和 "add" 操作 类 似 。 

。 "mod": % 操作 。 行为 和 "add" 操作 类 似 。 

。 "pow": ^ (次 方 ) 操作 。 行为 和 "add" 操作 类 似 。 

。"unm": - ( 取 负 ) 操作 。 行为 和 "add" 操作 类 似 。 

。 "idiv": // (向 下 取 整 除法 ) 操作 。 行为 和 "add" 操作 类 似 。 

。 "band": & ( 按 位 与 ) 操作 。 行为 和 "add" 操作 类 似 ， 不 同 的 是 Lua 会 在 任何 一 个 操 
作 数 无 法 转换 为 整数 时 (参见 $3.4.3) 党 试 取 元 方法 。 


。 "bor": | “【〔 按 位 或 ) 操作 。 行为 和 "band" 操作 类 似 。 
。 "bxor": ~ 【〔 按 位 异 或 ) 操作 。 行为 和 "band" 操作 类 似 。 
。"bnot": ~ 【〔 按 位 非 ) 操作 。 行为 和 "band" 操作 类 似 。 


。 "shl": &lt;&lt; 【〔 左 移 ) 操作 。 行为 和 "band" 操作 类 似 。 


"shr": &gt;&gt; 〈 右 移 ) 操作 。 行为 和 "band" 操作 类 似 。 

"concat": .. (连接 ) 操作 。 行为 和 "add" 操作 类 似 ， 不 同 的 是 Lua 在 任何 操作 数 即 
不 是 一 个 字符 串 也 不 是 数字 (数字 总 能 转换 为 对 应 的 字符 串 ) 的 情况 下 党 试 元 方法 。 
"len": # 【〔 取 长 度 ) 操作 。 如 果 对 象 不 是 字符 串 ，Lua 会 尝试 它 的 元 方法 。 如 果 有 元 
方法 ， 则 调用 它 并 将 对 象 以 参数 形式 传人 ， 而 返回 值 (被 调整 为 单个 ) 则 作为 结果 。 如 
果 对 象 是 一 张 表 且 没有 元 方法 ， Lua 使 用 表 的 取 长 度 操作 (参见 $S3.4.7) 。 其 它 情况 ， 
均 抛 出 错误 。 

"eq": == (等 于 ) 操作 。 和 "add" 操作 行为 类 似 ， 不 同 的 是 Lua 仅 在 两 个 值 都 是 表 或 
都 是 完全 用 户 数据 且 它 们 不 是 同一 个 对 象 时 才 尝 试 元 方法 。 调用 的 结果 总 会 被 转换 为 布 


尔 


han 


"It": &lt; (小 于 ) 操作 。 和 "add" 操作 行为 类 似 ， 不 同 的 是 Lua 仅 在 两 个 值 不 全 为 整 
数 也 不 全 为 字符 串 时 才 尝 试 元 方法 。 调用 的 结果 总 会 被 转换 为 布尔 量 。 

"le": &lt;= (小 于 等 于 ) 操作 。 和 其 它 操 作 不 同 ， 小 于 等 于 操作 可 能 用 到 两 个 不 同 的 
事件 。 首先 ， 像 "It" 操作 的 行为 那样 ，Lua 在 两 个 操作 数 中 查找 "_1le" 元 方法 。 如 果 
一 个 元 方法 都 找 不 到 ， 就 会 再 次 查找 "_1t "事件 ， 它 会 假设 a &lt;= b 等 价 于 

not (b &lt; a) 。 而 其 它 比 较 操 作 符 类 似 ， 其 结果 会 被 转换 为 布尔 量 。 

"index": 索引 table[key] 。 当 table 不 是 表 或 是 表 table 中 不 存在 key 这 个 键 
时 ， 这 个 事件 被 触发 。 此 时 ， 会 读 出 table 相应 的 元 方法 。 


尽管 名 字 取 成 这 样 ， 这 个 事件 的 元 方法 其 实 可 以 是 一 个 函数 也 可 以 是 一 张 表 。 如 果 它 是 
一 个 函数 ， 则 以 table 和 key 作为 参数 调用 它 。 如 果 它 是 一 张 表 ， 最 终 的 结果 就 是 以 
key 取 索 引 这 张 表 的 结果 。 【〔 这 个 索引 过 程 是 走 常规 的 流程 ， 而 不 是 直接 索引 ， 所 以 
这 次 索引 有 可 能 引发 另 一 次 元 方法 。) 


"newindex": 索引 赋值 table[key] = value 。 和 索引 事件 类 似 ， 它 发 生 在 table 不 是 
表 或 是 表 table 中 不 存在 key 这 个 键 的 时 候 。 此 时 ， 会 读 出 table 相应 的 元 方法 。 


同 素 引 过 程 那样 ， 这 个 事件 的 元 方法 即 可 以 是 画 数 ， 也 可 以 是 一 张 表 。 如 果 是 一 个 画 

数 ， 则 以 table 、 key 、 以 及 value 为 参数 传人 。 如 果 是 一 张 表 ， Lua 对 这 张 表 做 
索引 赋值 操作 。 《这 个 索引 过 程 是 走 常 规 的 流程 ， 而 不 是 直接 索引 赋值 ， 所 以 这 次 索引 
赋值 有 可 能 引发 另 一 次 元 方法 。) 

一 旦 有 了 "newindex" 元 方法 ， Lua 就 不 再 做 最 初 的 赋值 操作 。 (如 果 有 必要 ， 在 元 方 
法 内 部 可 以 调用 rawset 来 做 赋值 。) 


"call": 函数 调用 操作 func(args) 。 当 Lua 尝试 调用 一 个 非 范 数 的 值 的 时 候 会 触发 这 个 
事件 ( 即 func 不 是 一 个 豆 数 ) 。 查找 func 的 元 方法 ， 如 果 找 得 到 ， 就 调用 这 个 元 
方法 ， func 作为 第 一 个 参数 传 入 ， 原 来 调用 的 参数 ( args ) 后 依次 排 在 后 面 。 


2.5 - 垃圾 收集 


Lua 采用 了 自动 内 存 管 理 。 这 意味 着 你 不 用 操心 新 创建 的 对 象 需要 的 内 存 如 何 分 配 出 来 ， 也 
不 用 考虑 在 对 象 不 再 被 使 用 后 怎样 释放 它们 所 占用 的 内 存 。 Lua 运行 了 一 个 垃圾 收集 器 来 收 
集 所 有 死 对 象 〈 即 在 Lua 中 不 可 能 再 访问 到 的 对 象 ) 来 完成 自动 内 存 管理 的 工作 。 Lua 中 
所 有 用 到 的 内 存 ， 如 : 字符 串 、 表 、 用 户 数据 、 画 数 、 线 程 、 内 部 结构 等 ， 都 服从 自动 管 
理 。 


Lua 实现 了 一 个 增 量 标 记 - 打 描 收集 器 。 它 使 用 这 两 个 数字 来 控制 垃圾 收集 循环 : 垃圾 收集 器 
间歇 率 和 垃圾 收集 器 步 进 倍率 。 这 两 个 数字 都 使 用 百分数 为 单位 (例如 : 值 100 在 内 部 表 
示 1)。 


垃圾 收集 器 间歇 率 控制 着 收集 器 需要 在 开启 新 的 循环 前 要 等 竺 多久 。 增 大 这 个 值 会 减少 收集 
器 的 积极 性 。 当 这 个 值 比 100 小 的 时 候 ， 收 集 器 在 开启 新 的 循环 前 不 会 有 等 待 。 设置 这 个 值 
为 200 就 会 让 收集 器 等 到 总 内 存 使 用 量 达 到 之 前 的 两 倍 时 才 开 始 新 的 循环 。 


垃圾 收集 器 步 进 倍率 控制 着 收集 器 运作 速度 相对 于 内 存 分 配 速度 的 倍率 。 增 大 这 个 值 不 仅 会 
让 收集 器 更 加 积极 ， 还 会 增加 每 个 增 量 步骤 的 长 度 。 不 要 把 这 个 值 设 得 小 于 100 ， 那样 的 话 
收集 器 就 工作 的 太 慢 了 以 至 于 永远 都 干 不 完 一 个 循环 。 默认 值 是 200 ， 这 表示 收集 器 以 内 存 
分 配 的 “两 倍 ?" 速 工作 。 


如 果 你 把 步 进 倍率 设 为 一 个 非常 大 的 数字 (上 比 你 的 程序 可 能 用 到 的 字 节 数 还 大 10% ) ， 收 
集 器 的 行为 就 像 一 个 stop-the-world 收集 器 。 接着 你 若 把 间歇 率 设 为 200 ， 收集 器 的 行为 就 
和 过 去 的 Lua 版 本 一 样 了 : 每 次 Lua 使 用 的 内 存 翻 倍 时 ， 就 做 一 次 完整 的 收集 。 


你 可 以 通过 在 C 中 调用 lua_ gc 或 在 Lua 中 调用 collectgarbage 来 改变 这 俩 数字 。 这 两 个 
函数 也 可 以 用 来 直接 控制 收集 器 (例如 停止 它 或 重启 它 ) 。 


2.5.1 一 垃圾 收集 元 方法 


你 可 以 为 表 设 定 垃圾 收集 的 元 方法 ， 对 于 完全 用 户 数据 (参见 $2.4) ， 则 需要 使 用 C API 
。 该 元 方法 被 称 为 终结 器 。 终结 器 允许 你 配合 Lua 的 垃圾 收集 器 做 一 些 额 外 的 资源 管理 工 
作 (例如 关闭 文件 、 网 络 或 数据 库 连 接 ， 或 是 释放 一 些 你 自己 的 内 存 ) 。 


如 果 要 让 一 个 对 象 〈 表 或 用 户 数据 ) 在 收集 过 程 中 进入 终结 流程 ， 你 必须 标记 它 需 要 触发 终 
结 器 。 当 你 为 一 个 对 象 设置 元 表 时 ， 若 此 刻 这 张 元 表 中 用 一 个 以 字符 串 "gc " 为 索引 的 
域 ， 那 么 就 标记 了 这 个 对 象 需要 触发 终结 器 。 注意 : 如 果 你 给 对 象 设 置 了 一 个 没有 _gc 域 
的 元 表 ， 之 后 才 给 元 表 加 上 这 个 域 ， 那么 这 个 对 象 是 没有 被 标记 成 需要 触发 终结 器 的 。 然 
而 ， 一 旦 对 象 被 标记 ， 你 还 是 可 以 自由 的 改变 其 元 表 中 的 gc 域 的 。 


当 一 个 被 标记 的 对 象 成 为 了 垃圾 后 ， 垃圾 收集 器 并 不 会 立刻 回收 它 。 取而代之 的 是 ，Lua 会 
将 其 置 入 一 个 链表 。 在 收集 完成 后 ，Lua 将 通 历 这 个 链表 。 Lua 会 检查 每 个 链表 中 的 对 象 的 
_gc 元 方法 : 如 果 是 一 个 画 数 ， 那 么 就 以 对 象 为 唯一 参数 调用 它 ; 否则 直接 忽略 它 。 


在 每 次 垃圾 收集 循环 的 最 后 阶段 ， 本 次 循环 中 检测 到 的 需要 被 回收 之 对 象 ， 其 终结 器 的 触发 
次 序 按 当初 给 对 象 作 需 要 触发 终结 器 的 标记 之 次 序 的 逆序 进行 ; 这 就 是 说 ， 第 一 个 被 调用 的 
终结 器 是 程序 中 最 后 一 个 被 标记 的 对 象 所 携 的 那个 。 每 个 终结 器 的 运行 可 能 发 生 在 执行 常规 
代码 过 程 中 的 任意 一 刻 。 


由 于 被 回收 的 对 象 还 需要 被 终结 器 使 用 ， 该 对 象 ( 以 及 仅 能 通过 它 访问 到 的 其 它 对 象 ) 一定 
会 被 Lua 复活 。 通常 ， 复 活 是 短暂 的 ， 对 象 所 属 内 存 会 在 下 一 个 垃圾 收集 循环 释放 。 然后 ， 
若 终结 器 又 将 对 象 保存 去 一 些 全 局 的 地 方 (例如 : 放 在 一 个 全 局 变量 里 ) ， 这 次 复活 就 持续 
生效 了 。 此 外 ， 如 果 在 终结 器 中 对 一 个 正 进入 终结 流程 的 对 象 再 次 做 一 次 标记 让 它 触发 终结 
器 ， 只 要 这 个 对 象 在 下 个 循环 中 依旧 不 可 达 ， 它 的 终结 男 数 还 会 再 调用 一 次 。 无 论 是 哪 种 情 
况 ， 对 象 所 属 内 存 仅 在 垃圾 收集 循环 中 该 对 象 不 可 达 且 没有 被 标记 成 需要 触发 终结 器 才 会 被 
释放 。 


当 你 关闭 一 个 状态 机 (参见 lua_close ) ， Lua 将 调用 所 有 被 标记 了 需要 触发 终结 器 对 象 的 
终结 过 程 ， 其 次 序 为 标记 次 序 的 逆序 。 在 这 个 过 程 中 ， 任 何 终结 器 再 次 标记 对 象 的 行为 都 不 
会 生效 。 


2.5.2 -- 弱 表 


弱 表 指 内 部 元 素 为 弱 引用 的 表 。 垃圾 收集 器 会 忽略 掉 弱 引用 。 换 名 话说， 如果 一 个 对 象 只 
被 弱 引 用 引用 到 ， 垃圾 收集 器 就 会 回收 这 个 对 象 。 


一 张 弱 表 可 以 有 弱 键 或 是 弱 值 ， 也 可 以 键 值 都 是 弱 引 用 。 仅 含 有 弱 键 的 表 人 允许 收集 器 回收 它 
的 键 ， 但 会 阻止 对 值 所 指 的 对 象 被 回收 。 若 一 张 表 的 键 值 均 为 弱 引 用 ， 那么 收集 器 可 以 回收 
其 中 的 任意 键 和 值 。 任何 情况 下 ， 只 要 键 或 值 的 任意 一 项 被 回收 ， 相关 联 的 键 值 对 都 会 从 表 
中 移 除 。 一 张 表 的 元 表 中 的 _mode 域 控制 着 这 张 表 的 弱 属 性 。 当 _mode 域 是 一 个 包含 字 
符 ' k ' 的 字符 串 时 ， 这 张 表 的 所 有 键 此 为 弱 引 用 。 当 _mode 域 是 一 个 包含 字符 ' v' 的 字 
符 串 时 ， 这 张 表 的 所 有 值 此 为 弱 引 用 。 


属性 为 弱 键 强 值 的 表 也 被 称 为 暂时 表 。 对 于 一 张 暂 时 表 ， 它 的 值 是 否 可 达 仅 取决 于 其 对 应 键 
是 否 可 达 。 特别 注意 ， 如 果 表 内 的 一 个 键 仅仅 被 其 值 所 关联 引用 ， 这 个 键 值 对 将 被 表 内 移 
除 。 


对 一 张 表 的 弱 属 性 的 修改 仅 在 下 次 收集 循环 才 生 效 。 尤其 是 当 你 把 表 由 弱 改 强 ，Lua 还 是 有 
可 能 在 修改 生效 前 回收 表 内 一 些 项 目 。 


只 有 那些 有 显 式 构造 过 程 的 对 象 才 会 从 弱 表 中 移 除 。 值 ， 例 如 数字 和 轻 量 C 男 数 ， 不 受 垃圾 
收集 器 管辖 ， 因此 不 会 从 弱 表 中 移 除 (除非 它们 的 关联 项 被 回收 ) 。 虽然 字符 串 受 垃圾 回收 
器 管辖 ， 但 它们 没有 显 式 的 构造 过 程 ， 所 以 也 不 会 从 弱 表 中 移 除 。 


弱 表 针对 复活 的 对 象 〈 指 那些 正在 走 终结 流程 ， 信 能 被 终结 器 访问 的 对 象 ) 有 着 特殊 的 行 
为 。 弱 值 引 用 的 对 象 ， 在 运行 它们 的 终结 器 前 就 被 移 除 了 ， 而 弱 键 引用 的 对 象 则 要 等 到 终结 
器 运行 完毕 后 ， 到 下 次 收集 当 对 象 真 的 被 释放 时 才 被 移 除 。 这 个 行为 使 得 终结 器 运行 时 得 以 
访问 到 由 该 对 象 在 弱 表 中 所 关联 的 属性 。 


如 果 一 张 弱 表 在 当 次 收集 循环 内 的 复活 对 象 中 ， 那么 在 下 个 循环 前 这 张 表 有 可 能 未 被 正确 地 
清理 。 


2.6 -- 协 程 


Lua 支持 协 程 ， 也 叫 协同 式 多 线程 。 一 个 协 程 在 Lua 中 代表 了 一 段 独立 的 执行 线程 。 然 
而 ， 与 多 线程 系统 中 的 线程 的 区 别 在 于 ， 协 程 仅 在 显 式 调用 一 个 让 出 (yield) 本 数 时 才 挂 起 
当前 的 执行 。 


调用 辑 数 coroutine.create 可 创建 一 个 协 程 。 其 唯一 的 参数 是 该 协 程 的 主 画 数 。 create 
函数 只 负责 新 建 一 个 协 程 并 返回 其 句柄 (一 个 thread 类 型 的 对 象 ) ; 而 不 会 启动 该 协 程 。 


调用 coroutine.resume 函数 执行 一 个 协 程 。 第 一 次 调用 coroutine.resume 时 ， 第 一 个 参数 
应 传人 coroutine.create 返回 的 线程 对 象 ， 然 后 协 程 从 其 主 画 数 的 第 一 行 开始 执行 。 传递 给 
coroutine.resume 的 其 他 参数 将 作为 协 程 主 函 数 的 参数 传人 。 协 程 启动 之 后 ， 将 一 直 运 行 到 
它 终止 或 让 出 。 


协 程 的 运行 可 能 被 两 种 方式 终止 : 正常 途径 是 主 了 豆 数 返回 ( 显 式 返回 或 运行 完 最 后 一 条 指 
邻 ) ; 非 正 常 途径 是 发 生 了 一 个 未 被 捕获 的 错误 。 对 于 正常 结束 ， coroutine.resume 将 返 
回 true， 并 接 上 协 程 主 函 数 的 返回 值 。 当 错 误 发 生 时 ， coroutine.resume 将 返回 false 与 
昔 误 消息 。 


通过 调用 coroutine.yield 使 协 程 暂停 执行 ， 让 出 执行 权 。 协 程 让 出 时 ， 对 应 的 最 近 
coroutine.resume 图 数 会 立刻 返回 ， 即 使 该 让 出 操作 发 生 在 内 嵌 范 数 调用 中 ( 即 不 在 主 函 

数 ， 但 在 主 玉 数 直接 或 间接 调用 的 函数 内 部 ) 。 在 协 程 让 出 的 情况 下 ， coroutine.resume 也 
会 返回 true， 并 加 上 传 给 coroutine.yield 的 参数 。 当下 次 重启 同一 个 协 程 时 ， 协 程 会 接 
着 从 让 出 点 继续 执行 。 调用 coroutine.yield 会 返回 任何 传 给 coroutine.resume 的 第 一 个 参 
数 之 外 的 其 他 参数 。 


与 coroutine.create 类 似 ， coroutine.wrap 本 数 也 会 创建 一 个 协 程 。 不 同 之 处 在 于 ， 它 不 
返回 协 程 本 身 ， 而 是 返回 一 个 落 数 。 调用 这 个 男 数 将 启动 该 协 程 。 传递 给 该 函数 的 任何 参数 
均 当 作 coroutine.resume 的 额外 参数 。 coroutine.wrap 返回 coroutine.resume 的 所 有 返 
回 值 ， 除 了 第 一 个 返回 值 〈 布 尔 型 的 错误 码 ) 。 和 coroutine.resume 不 同 ， 

coroutine.wrap 不 会 捕获 错误 ; 而 是 将 任何 错误 都 传播 给 会 调用 者 。 


下 面 的 代码 展示 了 一 个 协 程 工 作 的 范例 : 


function foo (a) 

print("foo", a) 

return coroutine.yield(2*a) 
end 


co = coroutine.create(function (a,b) 
print("co-body", a, b) 
Jocal r = foo(a+1) 
print("co-body", r) 
local r, s = coroutine.yield(a+b, a-b) 
print("co-body", r, s) 
return b, "end" 

end) 


print("main", coroutine.resume(co, 1, 10)) 
print("main", coroutine.resume(co, "r")) 


print("main", coroutine.resume(co, "x", "y")) 

print("main", coroutine.resume(co, "x", "y")) 
当 你 运行 它 ， 将 产生 下 列 输 出 : 

co-body 1 10 

foo 2 

main true 4 

co-body r 

main true el -9 

co-body x y 

main true 10 end 

main false cannot resume dead coroutine 


你 也 可 以 通过 C API 来 创建 及 操作 协 程 : 参见 函数 lua newthread ， 
Jua yield 。 


Jua_resume ， 


以 及 


、 -= ~、 
3 一 语 避 定义 
这 一 章 描述 了 Lua 的 词法 、 语 法 和 句法 。 换 句 话说 ， 本 章 描述 哪些 符 记 是 有 效 的 ， 它们 如 何 
被 组 合 起 来 ， 这 些 组 合 方式 有 什么 含义 。 


关于 语言 的 构成 概念 将 用 常见 的 扩展 BNF 表达 式 写 出 。 也 就 是 这 个 样子 : {a} 表示 0 或 多 个 
a， [a] 表示 一 个 可 选 的 a。 可 以 被 分 解 的 非 最 终 符号 会 这 样 写 non-terminal ， 关键 字 会 写成 
这 样 kword， 而 其 它 不 能 被 分 解 的 最 终 符 号 则 写成 这 样 =' 。 完整 的 Lua 语法 可 以 在 本 手册 
最 后 一 章 §9 找到 。 


3.1 - 词法 约定 
Lua 语言 的 格式 自由 。 它 会 忽略 语法 元 素 ( 符 记 ) 间 的 空格 (包括 换行 ) 和 注释 ， 仅 把 它们 
看 作为 名 字 和 关键 字 间 的 分 割 符 。 


Lua 中 的 名 字 (也 被 称 为 标识 符 ) 可 以 是 由 非 数字 打头 的 任意 字母 下 划 线 和 数字 构成 的 字 
符 串 。 标识 符 可 用 于 对 变量 、 表 的 域 、 以 及 标签 命名 。 


下 列 关键 字 是 保留 的 ， 不 可 用 于 名 字 : 


and break do else elseif end 
false for function goto 1 in 
local nil not or repeat return 
then true until while 


Lua 语言 对 大 小 写 敏 感 : and 是 一 个 保留 字 , 但 And 与 AND 则 是 两 个 不 同 的 有 效 名 字 。 
作为 一 个 约定 ， 程 序 应 避免 创建 以 下 划 线 加 一 个 或 多 个 大 写字 母 构成 的 名 字 (例如 


_VERSION ) 。 


下 列 字符 串 是 另外 一 些 符 记 : 


十 和 / % # 
& ~ | << >> // 
一 一 号 二 = 2 一 < 2 二 


字面 串 可 以 用 单 引 号 或 双 引 号 括 起 。 字面 串 内 部 可 以 包含 下 列 C 风格 的 转 义 串 : " \a ' 〔( 响 
铃 ) ，' \bp ' ( 退 格 ) ，' \f' ( 换 页 ) ，' \n' (换行 ) ，' \r ' ( 回 车 ) ，' \t' ( 横 项 制 
表 ) ，' \v' 纵向 制 表 ) ，' \、' ( 反 斜 杠 ) ，' \"' ( 双 引 号 ) ， 以 及 '\''( 单 引号 )。 
在 反 斜 杠 后 跟 一 个 真正 的 换行 等 价 于 在 字符 串 中 写 一 个 换行 符 。 转 义 串 ' \z ' 会 忽略 其 后 的 
一 系列 空白 符 ， 包 括 换行 ; 它 在 你 需要 对 一 个 很 长 的 字符 串 常量 断 行为 多 行 并 希望 在 每 个 新 
行 保持 缩 进 时 非常 有 用 。 


Lua 中 的 字符 串 可 以 保存 任意 8 位 值 ， 其 中 包括 用 ' \6 ' 表示 的 0 。 一 般 而 言 ， 你 可 以 用 字 
符 的 数字 值 来 表示 这 个 字符 。 方式 是 用 转 义 串 \x_xx_ ， 此 处 的 XX 必须 是 恰好 两 个 字符 的 
16 进 制 数 。 或 者 你 也 可 以 使 用 转 义 串 \_ddd。， 这 里 的 qqq 是 一 到 三 个 十 进 制 数字 。 ( 注 
意 ， 如 果 在 转 义 符 后 接着 恰巧 是 一 个 数字 符号 的 话 ， 你 就 必须 在 这 个 转 义 形式 中 写 满 三 个 数 
字 。) 


对 于 用 UTF-8 编码 的 Unicode 字符 ， 你 可 以 用 转 义 符 \u{_xxx_} 来 表示 (这 里 必须 有 一 对 
花 括号 ) ， 此 处 的 XXX 是 用 16 进 制 表 示 的 字符 编号 。 


字面 串 还 可 以 用 一 种 长 括号 括 起 来 的 方式 定义 。 我 们 把 两 个 正 的 方 括号 间 插 入 n 个 等 号 定 
义 为 第 n 级 开 长 括号 。 就 是 说 ，0 级 开 的 长 括号 写作 [[ ， 一 级 开 长 括号 写作 [=[ ， 如 
此 等 等 。 闭 长 括号 也 作 类 似 定 义 ; 举 个 例子 ，4 级 反 的 长 括号 写作 ]====] 。 一 个 长 字面 
串 可 以 由 任何 一 级 的 开 长 括号 开始 ， 而 由 第 一 个 磁 到 的 同 级 的 闭 长 插 号 结束 。 这 种 方式 描述 
的 字符 串 可 以 包含 任何 东西 ， 当 然 特 定 级 别 的 反 长 括号 除外 。 整个 词法 分 析 过 程 将 不 受 分 行 
限制 ， 不 处 理 任何 转 义 符 ， 并 且 忽 略 掉 任何 不 同 级 别 的 长 括号 。 其 中 碰 到 的 任何 形式 的 换行 
串 〈 回 车 、 换 行 、 回 车 加 换行 、 换 行 加 回 车 ) ， 都 会 被 转换 为 单个 换行 符 。 


字面 串 中 的 每 个 不 被 上 述 规则 影响 的 字 节 都 呈现 为 本 身 。 然而 ，Lua 是 用 文本 模式 打开 源 文 
件 解析 的 ， 一 些 系统 的 文件 操作 茵 数 对 某 些 控制 字符 的 处 理 可 能 有 问题 。 因此 ， 对 于 非 文本 
数据 ， 用 引号 括 起 来 并 显 式 按 转 义 符 规则 来 表述 更 安全 。 


为 了 方便 起 见 ， 当 一 个 开 长 括号 后 紧 接 一 个 换行 符 时 ， 这 个 换行 符 不 会 放 在 字符 串 内 。 举 个 
例子 ， 假 设 一 个 系统 使 用 ASCI 码 〈 此 时 ' a ' 编码 为 97 ， 换行 编码 为 10 ，' 1 ' 编码 为 49 
) ， 下 面 五 种 方式 描述 了 完全 相同 的 字符 串 : 


"alLloNxn123" 
"alo\n123\"" 
'\9710\10\04923"" 
[[alo 

| 
[==[ 


上 ] ==] 


D 
Me dh LY 


oy 
Db 
WO 


数字 常量 (或 称 为 数字 量 ) 可 以 由 可 选 的 小 数 部 分 和 可 选 的 十 为 底 的 指数 部 分 构成 ， 指数 

部 分 用 字符 ' e ' 或 'E ' 来 标记 。 Lua 也 接受 以 ex 或 ex 开头 的 16 进 制 常量 。 16 进 制 常 
量 也 接受 小 数 加 指数 部 分 的 形式 ， 指 数 部 分 是 以 二 为 底 ， 用 字符 ' p ' 或 ' P ' 来 标记 。 数字 

常量 中 包含 小 数 点 或 指数 部 分 时 ， 被 认为 是 一 个 浮 点 数 ; 否则 被 认为 是 一 个 整数 。 下 面 有 一 
些 合法 的 整数 常量 的 例子 : 


3 345  Qxff  QxBEBADA 
以 下 为 合法 的 浮 点 常量 : 


3.0 3.1416 314.16e-2 0.31416E1 34e1 
Ox0O.1E OxA23p-4 OX1.921FB54442D18P+1 


在 字符 串 外 的 任何 地 方 出 现 以 双 横 线 ( -- ) 开头 的 部 分 是 注释 。 如 果 -- 后 没有 紧 跟 着 一 
个 开 大 括号 ， 该 注释 为 短 注 释 ， 注释 到 当前 行 末 截至 。 否则 ， 这 是 一 段 长 注释 ， 注释 区 
一 直 维 持 到 对 应 的 闭 长 括号 。 长 注释 通常 用 于 临时 屏蔽 掉 一 大 段 代 码 。 


3.2 - 交 星 


变量 是 储存 值 的 地 方 。 Lua 中 有 三 种 变量 : 全 局 变量 、 局 部 变量 和 表 的 域 。 


单个 名 字 可 以 指 代 一 个 全 局 变量 也 可 以 指 代 一 个 局 部 变量 (或 者 是 一 个 画 数 的 形 参 ， 这 是 一 
种 特殊 形式 的 局 部 变量 ) 。 


var ::= Name 


名 字 指 $S3.1 中 定义 的 标识 符 。 


所 有 没有 显 式 声明 为 局 部 变量 (参见 §3.3.7) 的 变量 名 都 被 当做 全 局 变量 。 局 部 变量 有 其 作 
用 范围 : 局 部 变量 可 以 被 定义 在 它 作 用 范围 中 的 函数 自由 使 用 (参见 $3.5) 。 


在 变量 的 首次 赋值 之 前 ， 变 量 的 值 均 为 nil。 


方 括号 被 用 来 对 表 作 索引 : 
Var = "prefixexp **[** exp ww |** 


对 全 局 变量 以 及 表 的 域 之 访问 的 含义 可 以 通过 元 表 来 改变 。 以 索引 方式 访问 一 个 变量 t[i] 

等 价 于 调用 gettable_event(t,i) 。 (参见 $2.4 ， 有 一 份 完整 的 关于 gettable_event 加 数 
的 说 明 。 这 个 画 数 并 没有 在 lua 中 定义 出 来 ， 也 不 能 在 lua 中 调用 。 这 里 我 们 把 提 到 它 只 是 
方便 说 明 问 题 。) 


var.Name 这 种 语法 只 是 一 个 语法 糖 ， 用 来 表示 var["Name"] : 


var ::= prefixexp ‘**.**’ Name 


对 全 局 变量 x 的 操作 等 价 于 操作 _ENv.x 。 由 于 代码 块 编译 的 方式 ， _ENv 永远 也 不 可 能 
是 一 个 全 局 名 字 (参见 §2.2) 。 


3.3 一 语句 


Lua 支持 所 有 与 Pascal 或 是 C 类 似 的 常见 形式 的 语句 ， 这 个 集合 包 插 赋值， 控制 结构 ， 邢 
数 调用 ， 还 有 变量 声明 。 


3.3.1 一 语句 块 


语句 块 是 一 个 语句 序列 ， 它 们 会 按 次 序 执行 : 


block ::= {stat} 


Lua 支持 空 语句 ， 你 可 以 用 分 号 分 割 语句 ， 也 可 以 以 分 号 开始 一 个 语句 块 ， 或 是 连 着 写 两 个 


分 号 : 


Sa = 人 


画 数 调 用 和 赋值 语句 都 可 能 以 一 个 小 括号 打头 ， 这 可 能 让 Lua 的 语法 产生 歧义 。 我 们 来 看 看 
下 面 的 代码 片断 : 


a=b+c 
(print or io.write)('done') 


从 语法 上 说 ， 可 能 有 两 种 解释 方式 : 


a= b+ c(print or io.write)('done') 


a=b+c; (print or io.write)('done') 


当前 的 解析 器 总 是 用 第 一 种 结构 来 解析 ， 它 会 将 开 括 号 看 成 汞 数 调用 的 参数 传递 开始 处 。 为 
了 避免 这 种 二 义 性 ， 在 一 条 语句 以 小 括号 开头 时 ， 前 面 放 一 个 分 号 是 个 好 习惯 : 


;(print or io.write)('done') 
一 个 语句 块 可 以 被 显 式 的 定 界 为 单条 语句 : 


statne: = “do block +*ende* 


显 式 的 对 一 个 块 定 界 通常 用 来 控制 内 部 变量 声明 的 作用 域 。 有 时 ， 显 式 定 界 也 用 于 在 一 个 语 
句 块 中 间 插 入 return (参见 83.3.4) 。 


3.3.2 一 代码 块 


Lua 的 一 个 编译 单元 被 称 为 一 个 代码 块 。 从 名 法 构成 上 讲 ， 一 个 代码 块 就 是 一 个 语句 块 。 
chunk ::= block 
Lua 把 一 个 代码 块 当 作 一 个 拥有 不 定 人 参数 的 匿名 函数 (参见 83.4.11) 来 处 理 。 正 是 这 样 ， 代 


码 块 内 可 以 定义 局 部 变量 ， 它 可 以 接收 人 参数， 返回 若干 值 。 此 外 ， 这 个 匿名 本 数 在 编译 时 还 
为 它 的 作用 域 绑 定 了 一 个 外 部 局 部 变量 _ENv (参见 $2.2) 。 该 函数 总 是 把 _ENv 作为 它 


唯一 的 一 个 上 值 ， 即使 这 个 男 数 不 使 用 这 个 变量 ， 它 也 存在 。 


代码 块 可 以 被 保存 在 文件 中 ， 也 可 以 作为 宿主 程序 内 部 的 一 个 字符 串 。 要 执行 一 个 代码 块 ， 
首先 要 让 Lua 加 载 它 ， 将 代码 块 中 的 代码 预 编译 成 虚拟 机 中 的 指令 ， 而 后 ，Lua 用 虚拟 机 
解释 器 来 运行 编译 后 的 代码 。 


代码 块 可 以 被 预 编 译 为 二 进 制 形 式 ; 参见 程序 luac 以 及 贺 数 string.dump 可 获得 更 多 细 
节 。 用 源码 表示 的 程序 和 编译 后 的 形式 可 自由 替换 ; Lua 会 自动 检测 文件 格式 做 相应 的 处 理 
(参见 load ) o 


3.3.3 -- 赋值 


Lua 多 许多 重 赋值 。 因此 ， 赋 值 的 语法 定义 是 等 号 左边 放 一 个 变量 列表 ， 而 等 号 右边 放 一 
表达 式 列 表 。 两 边 的 列表 中 的 元 素 都 用 逗号 间 开 : 


stat ::= varlist ‘**=**’ explist 
varlist ::= Var {**,**’ Var 
explist ::= exp { **,**" exp} 


表达 式 放 在 $S3.4 中 讨论 。 


在 作 赋 值 操作 之 前 ， 那 值 列表 会 被 调整 为 左边 变量 列表 的 个 数 。 如 果 值 比 需要 的 更 多 的 
话 ， 多 余 的 值 就 被 扔 掉 。 如 果 值 的 数量 不 够 需求 ， 将 会 按 所 需 扩展 若干 个 nil。 如 果 表 达 式 
列表 以 一 个 图 数 调用 结束 ， 这 个 函数 所 返回 的 所 有 值 都 会 在 调整 操作 之 前 被 置信 值 列表 中 
《除非 这 个 函数 调用 被 用 括号 括 了 起 来 ; 参见 83.4) 。 


赋值 语句 首先 让 所 有 的 表达 式 完成 运算 ， 之 后 再 做 赋值 操作 。 因此 ， 下 面 这 段 代 码 


5 
i, a[i] = i+1, 20 


会 把 a[3] 设置 为 20， 而 不 会 影响 到 a[4] 。 这 是 因为 a[i] 中 的 i 在 被 赋值 为 4 之 前 
就 被 计算 出 来 了 (当时 是 3 ) 。 简单 说 ， 这 样 一 行 


2 NMA 2% 


交换 x 和 y 的 值 ， 及 


对 全 局 变量 以 及 表 的 域 的 赋值 操作 的 含义 可 以 通过 元 表 来 改变 。 对 t[i] = val 这 样 的 变量 
索引 赋值 ， 等 价 于 settable_event(t,i,val) 。 【关于 阔 数 settable_event 的 详细 说 明 ， 参 
见 $2.4。 这 个 函数 并 没有 在 Lua 中 定义 出 来 ， 也 不 可 以 被 调用 。 这 里 我 们 列 出 来 ， 仅 仅 出 
于 方便 解释 的 目的 。) 


对 于 全 局 变量 x = val 的 赋值 等 价 于 _ENV.x = val (参见 §2.2) 。 


3.3.4 -- 控制 结构 


if, while, and repeat 这 些 控制 结构 符合 通常 的 意义 ， 而 且 也 有 类 似 的 语法 : 


stat = **while** exp **do** block **end** 
stat ::= **repeat** block **until** exp 
stat = **jf** exp **then** block {**elseif** exp **then** block} [**else** block] * 


Lua 也 有 一 个 for 语句 ， 它 有 两 种 形式 (参见 $3.3.5) 。 





控制 结构 中 的 条 件 表 达 式 可 以 返回 任何 值 。 false 与 nil 两 者 都 被 认为 是 假 。 所 有 不 同 于 nil 
与 false 的 其 它 值 都 被 认为 是 真 (特别 需要 注意 的 是 ， 数 字 0 和 空 字符 串 也 被 认为 是 真 ) 。 


在 repeat-until 循环 中 ， 内 部 语句 块 的 结束 点 不 是 在 until 这 个 关键 字 处 ， 它 还 包括 了 其 后 
的 条 件 表达 式 。 因此 ， 条 件 表达 式 中 可 以 使 用 循环 内 部 语句 块 中 的 定义 的 局 部 变量 。 


goto 语句 将 程序 的 控制 点 转移 到 一 个 标签 处 。 由 于 句法 上 的 原因 ， Lua 里 的 标签 也 被 认为 


是 语句 : 
Stat ::= **goto** Name 
stat ::= label 
abels = Name 


除了 在 内 启 画 数 中 ， 以 及 在 内 嵌 语 句 块 中 定义 了 同名 标签 ， 的 情况 外 ， 标签 对 于 它 定 义 所 在 
的 整个 语句 块 可 见 。 只 要 goto 没有 进入 一 个 新 的 局 部 变量 的 作用 域 ， 它 可 以 跳 转 到 任意 可 见 
标签 处 。 


标签 和 没有 内 容 的 语句 被 称 为 空 语句 ， 它 们 不 做 任何 操作 。 
break 被 用 来 结束 while、 repeat、 或 for 循环 ， 它 将 跳 到 循环 外 接着 之 后 的 语句 运行 : 


stat ::= **break** 


break 跳出 最 内 层 的 循环 。 


return 被 用 于 从 函数 或 是 代码 块 (其 实 它 就 是 一 个 函数 ) 中 返回 值 。 画 数 可 以 返回 不 止 一 个 
值 ， 所 以 return 的 语法 为 


stat meBune explastin ee 多 | 


return 只 能 被 写 在 一 个 语句 块 的 最 后 一 句 。 如 果 你 真 的 需要 从 语句 块 的 中 间 return， 你 可 以 
使 用 显 式 的 定义 一 个 内 部 语句 块 ， 一般 写作 do return end 。 可 以 这 样 守 是 因为 现在 return 
成 了 内部) 语句 块 的 最 后 一 句 了 。 

3.3.5 - For 语句 

for 有 两 种 形式 : 一 种 是 数字 形式 ， 另 一 种 是 通用 形式 。 

数字 形式 的 for 循环 ， 通 过 一 个 数学 运算 不 断 地 运行 内 部 的 代码 块 。 下 面 是 它 的 语法 : 


坊 卡 安 牙 es OF Name 4 大 大 一 炎炎 了 exp 2 exp ES exp] wd [0 i block wT ee 


block 将 把 name 作 循 环 变量 。 从 第 一 个 exp 开始 起 ， 直 到 第 二 个 exp 的 值 为 止 ， 其 步 长 为 
第 三 个 exp 。 更 确切 的 说 ， 一 个 for 循环 看 起 来 是 这 个 样子 


formv ee2 > ed domblockaend 





这 等 价 于 代码 : 


do 
local _var_, _limit_ , _step_ = tonumber(_e1 ), tonumber(_e2_), tonumber(_e3_) 
if not (_var_ and _limit_ and _step_) then error() end 
var_= var_- _step 
while true do 
var_= var_+ _step 
If (_step_ >= 0 and _var_ > _limit_ ) or (_step_ < 0 and var_ < _limit_) then 
break 
end 
local v = _var_ 
_block_ 
end 
end 




















注意 下 面 这 几 点 : 


。 所 有 三 个 控制 表达 式 都 只 被 运算 一 次 ， 表达 式 的 计算 在 循环 开始 之 前 。 这 些 表达 式 的 结 
果 必 须 是 数字 。 

© var ， limit ， 以 及 _step” 都 是 一 些 不 可 见 的 变量 。 这 里 给 它们 起 的 名 字 都 仅仅 
用 于 解释 方便 。 

。 如 果 第 三 个 表达 式 ( 步 长 ) 没有 给 出 ， 会 把 步 长 设 为 1。 

。 你 可 以 用 break 和 goto 来 退出 for 循环 。 

。 循环 变量 v 是 一 个 循环 内 部 的 局 部 变量 ; 如 果 你 需要 在 循环 结束 后 使 用 这 个 值 ， 在 退 
出 循环 前 把 它 赋 给 另 一 个 变量 。 





通用 形式 的 for 通过 一 个 叫 作 迭代 器 的 辑 数 工作 。 每 次 迭代 ， 和 迭代 器 函数 都 会 被 调用 以 产生 
一 个 新 的 值 ， 当 这 个 值 为 nil 时 ， 循 环 停止 。 通用 形式 的 for 循环 的 语法 如 下 : 


stat 三 本 “2 人 On mamelistq *1n explist**do** block **ende” 
namelist ::= Name {**,**’ Name} 

这 样 的 for 语句 
for _var 1 ，'…'， _ var_n in _explist_ do _block_ end 


它 等 价 于 这 样 一 段 代码 : 


do 
local _f , _s , _var_ = _explist_ 
while true do 
local var 1 , ''', Vvar n_=_f ( s , _var) 
if var 1 == nil then break end 
var_= _var_1 
_block_ 
end 
end 











注意 以 下 几 点 : 
@ explist 只 会 被 计算 一 次 。 它 返回 三 个 值 ， = 人 迭代 器 轴 数 ， = 状态 ， 一 个 迫 
代 器 的 初始 值 。 
ee。 f ，_s ,与 _var 都 是 不 可 见 的 变量 。 这 里 给 它们 起 的 名 字 都 只 是 为 了 解说 方 
便 。 
。 你 可 以 使 用 break 来 跳出 for 循环 。 
e。 环 变 量 _var_i 对 于 循环 来 说 是 一 个 局 部 变量 ; 你 不 可 以 在 for 循环 结束 后 继续 使 用 。 
如 果 你 需要 保留 这 些 值 ， 那 么 就 在 循环 跳出 或 结束 前 赋值 到 别 的 变量 里 去 。 
3.3.6 -- 贺 数 调用 语句 
为 了 人 允许 使 用 函数 的 副作用 ， 函数 调用 可 以 被 作为 一 个 语句 执行 : 


stat ::= functioncall 
在 这 种 情况 下 ， 所 有 的 返回 值 都 被 舍弃 。 画 数 调 用 在 S3.4.10 中 解释 。 


3.3.7 - 局 部 声明 
局 部 变量 可 以 在 语句 块 中 任何 地 方 声明 。 声明 可 以 包含 一 个 初始 化 赋值 操作 : 


Stat ::= **]1ocal** namelist [‘**=**’ explist] 


如 果 有 初始 化 值 的 话 ， 初 始 化 赋值 操作 的 语法 和 赋值 操作 一 致 (参见 83.3.3 ) 。 若 没 有 初始 
化 值 ， 所 有 的 变量 都 被 初始 化 为 nil。 


一 个 代码 块 同时 也 是 一 个 语句 块 (参见 $S3.3.2) ， 所 以 局 部 变量 可 以 放 在 代码 块 中 那些 显 式 
注 明 的 语句 块 之 外 。 


局 部 变量 的 可 见 性 规则 在 S3.5 中 解释 。 


3.4 -表达 式 


Lua 中 有 这 些 基本 表达 式 : 


exp ::= prefixexp 

exp := **niLl** | **faLlse** | true** 

exp ::= Numeral 

exp ::= LiteralString 

exp ::= functiondef 

exp ::= tableconstructor 

XD = 

exp ::= exp binop exp 

exp ::= unop exp 

prefixexp "=> Var lfunctroncalnl (exp SY 


数字 和 字面 串 在 S3.1 中 解释 ; 变量 在 83.2 中 解释 ; 男 数 定义 在 $3.4.11 中 解释 ; 画 数 调用 
在 83.4.10 中 解释 ; 表 的 构造 在 $3.4.9 中 解释 。 可 变 参 数 的 表达 式 写作 三 个 点 (' ... ') ， 
它 只 能 在 有 可 变 参 数 的 函数 中 直接 使 用 ; 这 些 在 S3.4.11 中 解释 。 


二 元 操作 符 包 含有 数学 运算 操作 符 (参见 $3.4.1) ， 位 操作 符 (参见 $3.4.2) ， 比较 操作 符 

(参见 S3.4.4) ， 逻辑 操作 符 (参见 83.4.5) ， 以 及 连接 操作 符 (参见 $3.4.6) 。 一 元 操 
作 符 包括 负 号 (参见 S3.4.1) ， 按 位 非 (参见 83.4.2) ， 逻辑 非 (参见 $3.4.5) ， 和 取 长 
度 操作 符 (参见 §3.4.7) 。 


玉 数 调用 和 可 变 人 参数 表达 式 都 可 以 放 在 多 重 返 回 值 中 。 如 果 事 数 调 用 被 当 作 一 条 语句 参见 

§3.3.6) ， 其 返回 值 列表 被 调整 为 堆 个 元 素 ， 即 抛弃 所 有 的 返回 值 。 如 果 表 达 式 被 用 于 表达 

式 列表 的 最 后 (或 是 唯一 的 ) 一 个 元 素 ， 那么 不 会 做 任何 调整 (除非 表达 式 被 括号 括 起 

来 ) 。 在 其 它 情况 下 ， Lua 都 会 把 结果 调整 为 一 个 元 素 置 入 表达 式 列 表 中 ， 即 保留 第 一 个 结 
而 忽略 之 后 的 所 有 值 ， 或 是 在 没有 结果 时 ， 补 单个 nil。 


这 里 有 一 些 例子 : 


f() -- 调整 为 9 个 结果 


TU) -- f() 会 被 调整 为 一 个 结果 

g(x, f()) -- g 收 到 x 以 及 f() 返回 的 所 有 结果 
arbrc 让 (EX -- f() 被 调整 为 1 个 结果 (c 收 到 nil) 
El EE -- a 收 到 可 变 参 数列 表 的 第 一 个 参数 ， 


-- b 收 到 第 二 个 参数 (如果 可 变 参 数列 表 中 
- 没有 实际 的 参数 ，a 和 b 都 会 收 到 nil) 


a Xf -- f() 被 调整 为 2 个 结果 

a,b,c = f() -- f() 被 调整 为 3 个 结果 

return f() -- 返回 f() 的 所 有 返回 结果 

return ... - - 返回 从 可 变 参 数列 表 中 接收 到 的 所 有 参数 parameters 
return x,y,f() -- 返回 x，y， 以 及 f() 的 所 有 返回 值 

{f()} -- 用 f() 的 所 有 返回 值 创 建 一 个 列表 

hs -- 用 可 变 参数 中 的 所 有 值 创建 一 个 列表 

{f(), nil} -- f() 被 调整 为 一 个 结果 


被 括号 括 起 来 的 表达 式 永远 被 当 作 一 个 值 。 所 以 ， (f(x,y,z)) 即使 f 返回 多 个 值 ， 这 个 
表达 式 永远 是 一 个 单一 值 。 ( (f(x,y,z)) 的 值 是 f 返回 的 第 一 个 值 。 如 果 f 不 返回 值 
的 话 ， 那 么 它 的 值 就 是 nil 。) 


3.4.1 一 数学 运算 操作 符 
Lua 支持 下 列 数学 运算 操作 符 : 


。 + :加 法 

。 - :减法 

。 * :乘法 

。 / : 浮 点 除法 

e。 // :向 下 取 整 除法 
。 % : 取 模 

。 ^ : 乘 方 

。 - : 取 负 


除了 乘 方 和 浮 点 除法 运算 ， 数学 运算 按 如 下 方式 工作 : 如 果 两 个 操作 数 都 是 整数 ， 该 操作 以 
整数 方式 操作 且 结 果 也 将 是 一 个 整数 。 否则 ， 当 两 个 操作 数 都 是 数字 或 可 以 被 转换 为 数字 的 
字符 串 (参见 §3.4.3) 时 ， 操作 数 会 被 转换 成 两 个 浮 点 数 ， 操作 按 通 常 的 浮 点 规则 〈 一 般 遵 
循 IEEE 754 标准 ) 来 进行 ， 结 果 也 是 一 个 浮 点 数 。 


乘 方 和 浮 点 除法 ( / ) 总 是 把 操作 数 转 换 成 浮 点 数 进行 ， 其 结果 总 是 浮 点 数 。 乘 方 使 用 
ISO C 画 数 pow ， 因此 它 也 可 以 接受 非 整 数 的 指数 。 


向 下 取 整 的 除法 ( // ) 指 做 一 次 除法 ， 并 将 商 圆 整 到 靠近 穷 的 一 侧 ， 即 对 操作 数 做 除 
法 后 取 floor 。 


取 模 被 定义 成 除法 的 余数 ， 其 商 被 圆 整 到 靠近 负 无 穷 的 一 侧 〈 向 下 取 整 的 除法 ) 。 


对 于 整数 数学 运算 的 浴 出 问题 ， 这 些 操作 采取 的 策略 是 按 通常 遵循 的 以 2 为 补 码 的 数学 运算 
的 环绕 规则 。 【〔 换 句 话说 ， 它 们 返回 其 运算 的 数学 结果 对 2<sup>64</sup> 取 模 后 的 数 
字 。) 


3.4.2 - 位 操作 符 
Lua 支持 下 列 位 操作 符 : 


。 & : 按 位 与 

。 | : 按 位 或 

。 ~ : 按 位 异 或 

。 &gt;&gt; : 右 移 
。 &lt;&lt; : 左 移 
。 -~ : 按 位 非 


所 有 的 位 操作 都 将 操作 数 先 转换 为 整数 (参见 $3.4.3) ， 然后 按 位 操作 ， 其 结果 是 一 个 整 
数 。 


对 于 右 移 和 左 移 ， 均 用 需 来 填补 空位 。 移动 的 位 数 若 为 负 ， 则 向 反方 向 位 移 ; 若 移 动 的 位 数 
的 绝对 值 大 于 等 于 整数 本 身 的 位 数 ， 其 结果 为 雳 (所 有 位 都 被 移出 ) 。 


3.4.3 一 强制 转换 


Lua 对 一 些 类 型 和 值 的 内 部 表示 会 在 运行 时 做 一 些 数学 转换 。 位 操作 总 是 将 浮 点 操作 数 转换 
成 整数 。 乘 方 和 浮 点 除法 总 是 将 整数 转换 为 浮 点 数 。 其 它 数 学 操作 若 针 对 混合 操作 数 (整数 
和 浮 点 数 ) 将 把 整数 转换 为 浮 点 数 ; 这 一 点 被 称 为 通常 规则 。 C API 同样 会 按 需 把 整数 转换 
为 浮 点 数 以 及 把 浮 点 数 转换 为 整数 。 此 外 ， 字 符 串 连接 操作 除了 字符 串 ， 也 可 以 接受 数字 作 
为 参数 。 


当 操作 需要 数字 时 ，Lua 还 会 把 字符 串 转 换 为 数字 。 


当 把 一 个 整数 转换 为 浮 点 数 时 ， 若 整数 值 恰 好 可 以 表示 为 一 个 浮 点 数 ， 那 就 取 那 个 浮 点 数 。 
否则 ， 转 换 会 取 最 接近 的 较 大 值 或 较 小 值 来 表示 这 个 数 。 这 种 转换 是 不 会 失败 的 。 

将 浮 点 数 转 为 整数 的 过 程 会 检查 浮 点 数 能 否 被 准确 的 表达 为 一 个 整数 〈 即 ， 浮 点 数 是 一 个 整 
数值 且 在 整数 可 以 表达 的 区 间 ) 。 如 果 可 以 ， 结 果 就 是 那个 数 ， 否 则 转换 失败 。 

从 字符 串 到 数字 的 转换 过 程 遵循 以 下 流程 : 首先 ， 遵 循 按 Lua 词法 分 析 器 的 规则 分 析 语 法 来 
转换 为 对 应 的 整数 或 浮 点 数 。 (字符 串 可 以 有 前 置 或 后 置 的 空格 以 及 一 个 符号 。) 然后 ， 结 
果 数 字 再 按 前 述 规则 转换 为 所 需要 的 类 型 〈 浮 点 或 整数 ) 。 


从 数字 转换 为 字符 串 使 用 非 指 定 的 人 可 读 的 格式 。 若 想 完 全 控制 数字 到 字符 串 的 转换 过 程 ， 
可 以 使 用 字符 串 库 中 的 format 回 数 (参见 string.format ) 。 


3.4.4 - 比较 操作 符 
Lua 支持 下 列 比 较 操作 符 : 


。 == : 等 于 

。 -= : 不 等 于 

e。 &lt; :小 于 

© &gt; : 大 于 

e &1t;= : 小 于 等 于 
。 &gt;= : 大 于 等 于 


这 些 操作 的 结果 不 是 false 就 是 true。 


等 于 操作 ( == ) 先 比 较 操 作 数 的 类 型 。 如 果 类 型 不 同 ， 结 果 就 是 false。 否则 ， 继 续 比较 
值 。 字符 串 按 一 般 的 方式 比较 。 数字 遵循 二 元 操作 的 规则 : 如 果 两 个 操作 数 都 是 整数 ， 它 
们 按 整 数 比较 ; 否则 ， 它 们 先 转换 为 浮 点 数 ， 然 后 再 做 比较 。 


表 ， 用 户 数据 ， 以 及 线程 都 按 引 用 比较 : 只 有 两 者 引用 同一 个 对 象 时 才 认 为 它们 相等 。 每 次 
你 创建 一 个 新 对 象 〈 一 张 表 ， 一 个 用 户 数据 ， 或 一 个 线程 ) ， 新 对 象 都 一 定 和 已 有 且 存 在 的 
对 象 不 同 。 相同 引用 的 闭 包 一 定 相 等 。 有 任何 可 察觉 的 差异 〈 不 同 的 行为 ， 不 同 的 定义 ) 一 
定 不 等 。 


你 可 以 通过 使 用 "eq" 元 方法 (参见 $2.4) 来 改变 Lua 比较 表 和 用 户 数据 时 的 方式 。 
等 于 操作 不 会 将 字符 串 转 换 为 数字 ， 反 之 亦 然 。 即 ， "6"==6 结果 为 false， 且 tro] 与 
t["e"] 指 代 着 表 中 的 不 同 项 。 

= 操作 完全 等 价 于 ( == ) 操作 的 反 值 。 
大 小 比较 操作 以 以 下 方式 进行 。 如 果 参 数 都 是 数字 ， 它们 按 二 元 操作 的 常规 进行 。 否则 ， 如 
果 两 个 参数 都 是 字符 串 ， 它们 的 值 按 当前 的 区 域 设 置 来 比较 。 再 则 ，Lua 就 试 着 调用 "It" 或 
是 "le" 元 方法 (参见 $2.4) 。 a &gt; b 的 比较 被 转译 为 b &lt; a ， a &gt;= b 被 转译 为 


b &lt;= aio 


3.4.5 -- 逻辑 操作 符 


Lua 中 的 逻辑 操作 符 有 and， or， 以 及 not。 和 控制 结构 (参见 83.3.4) 一 样 ， 所 有 的 远 辑 
操作 符 把 false 和 nil 都 作为 假 ， 而 其 它 的 一 切 都 当 作 真 。 


取 反 操作 not 总 是 返回 false 或 true 中 的 一 个 。 与 操作 符 and 在 第 一 个 参数 为 false 或 nil 
时 返回 这 第 一 a 否则 ，and 返回 第 二 个 参数 。 或 操作 符 or 在 第 一 个 参数 不 为 nil 也 
不 为 false 时 ， 返回 这 第 一 个 参数 ， 否 则 返回 第 二 个 参数 。 and 和 or 都 遵循 短路 规则 ; 也 
就 是 说 ， 第 二 个 操作 数 只 在 需要 的 时 候 去 求 值 。 这 里 有 一 些 例子 


10 or 20 之 


10 or error() --> 10 
nil or i ee i 
nil and 10 --> nil 
false and error() --> false 
false and nil --> false 
false or nil --> nil 
10 and 20 --> 20 


(在 这 本 手册 中 ， --&gt; 指 前 面 表达 式 的 结果 。) 


3.4.6 - 字符 串 连 接 


Lua 中 字符 串 的 连接 操作 符 写作 两 个 点 ('.. ') 。 如 果 两 个 操作 数 都 是 字符 串 或 都 是 数字 ， 
连接 操作 将 以 §3.4.3 中 提 到 的 规则 把 其 转换 为 字符 串 。 否则 ， 会 调用 元 方法 _concat  ( 参 
见 S2.4) 。 


3.4.7 - 取 长 度 操作 符 


取 长 度 操作 符 写作 一 元 前 置 符 # 。 字符 串 的 长 度 是 它 的 字 节 数 〈 就 是 以 一 个 字符 一 个 字 节 计 
算 的 字符 串 长 度 ) 。 


程序 可 以 通过 _1len 元 方法 (参见 $2.4) 来 修改 对 字符 串 类 型 外 的 任何 值 的 取 长 度 操作 行 


如 果 _1en 元 方法 没有 给 出 ， 表 t 的 长 度 只 在 表 是 一 个 序列 时 有 定义 。 序列 指 表 的 正 数 
键 集 等 于 {1..n7 ， 其 中 n 是 一 个 非 负 整 数 。 在 这 种 情况 下 ，n 是 表 的 长 度 。 注意 这 样 的 表 


{10, 20, nil, 40} 


不 是 一 个 序列 ， 因 为 它 有 键 4 却 没有 键 3 。 (因此 ， 该 表 的 正 整数 键 集 不 等 于 {1..n) 集 
合 ， 故 而 就 不 存在 n。) 注意 ， 一 张 表 是 否 是 一 个 序列 和 它 的 非 数字 键 无 关 。 


3.4.8 - 优先 级 
Lua 中 操作 符 的 优先 级 写 在 下 表 中 ， 从 低 到 高 优先 级 排序 : 


< 2 = = ~ 二 一 一 


A // % 
unary operators (not # - 3 
人 


通常 ， 你 可 以 用 括号 来 改变 运算 次 序 。 连接 操作 符 ( ..') 和 乘 方 操作 ( ^ ') 是 从 右 至 左 的 。 
其 它 所 有 的 操作 都 是 从 左 至 右 。 


3.4.9 -- 表 构 建 


表 构 造 子 是 一 个 构造 表 的 表达 式 。 每 次 构造 子 被 执行 ， 都 会 构造 出 一 张 新 的 表 。 构造 子 可 以 
被 用 来 构造 一 张 空 表 ， 也 可 以 用 来 构造 一 张 表 并 初始 化 其 中 的 一 些 域 。 一 般 的 构造 子 的 语法 
如 下 


tableconstructor® := (ifrieLldlist | 

fieldlist ::= field {fieldsep field} [fieldsep] 

GLd 二 一， | exp a ee 4 类 二 炎炎 了 exp | Name 4 大 大 一 大 大 了 exp | exp 
fieldsep < 一， 人 | 


每 个 形 如 [exp1] = exp2 的 域 向 表 中 增加 新 的 一 项 ， 其 键 为 exp1 而 值 为 exp2 。 形 如 
name = exp 的 域 等 价 于 ["name"] = exp 。 最 后 ， 形 如 exp 的 域 等 价 于 [il = exp ， 这 
里 的 i 是 一 个 从 1 开始 不 断 增 长 的 数字 。 这 这 个 格式 中 的 其 它 域 不 会 破坏 其 记 数 。 举 个 例 
于: 


a= { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 } 


等 价 于 

do 
local t = 人 
CC sad 
t[1] = "x -- 1st exp 
t[2] = "y" -- 2nd exp 
Tl ee tu le = 
t[3] = f(x) -- 3rd exp 
t[30] = 23 
t[4] = 45 -- 4th exp 
a=t 

end 


构造 子 中 赋值 的 次 序 未 定义 。 〔 次 序 问题 只 会 对 那些 键 重复 时 的 情况 有 影响 。) 


如 果 表 单 中 最 后 一 个 域 的 形式 是 exp ， 而 且 其 表达 式 是 一 个 函数 调用 或 者 是 一 个 可 变 参 
数 ， 那么 这 个 表达 式 所 有 的 返回 值 将 依次 进入 列表 (参见 $3.4.10) 。 


初始 化 域 表 可 以 在 最 后 多 一 个 分 割 符 ， 这 样 设 计 可 以 方便 由 机 器 生成 代码 。 
3.4.10 -- 画 数 调用 
Lua 中 的 函数 调用 的 语法 如 下 : 


functioncall ::= prefixexp args 


函数 调用 时 ， 第 一 步 ，prefixexp 和 args 先 被 求 值 。 如 果 prefixexp 的 值 的 类 型 是 function， 
那么 这 个 男 数 就 被 用 给 出 的 参数 调用 。 否则 prefixexp 的 元 方法 "call" 就 被 调用 ， 第 一 个 参数 
是 prefixexp 的 值 ， 接 下 来 的 是 原来 的 调用 参数 (参见 $S2.4) 。 


这 样 的 形式 


functioncall ::= prefixexp ‘**:**’ Name args 


可 以 用 来 调用 "方法 "。 这 是 Lua 支持 的 一 种 语法 糖 。 像 v:name(args) 这 个 样子 ， 被 解释 成 
Vv.nName(v,args) ， 这 里 的 V 只 会 被 求 值 一 次 。 


参数 的 语法 如 下 : 
args 一 (5 [explist] SD 
args ::= tableconstructor 
args ::= LiteralString 


所 有 参数 的 表达 式 求 值 都 在 函数 调用 之 前 。 这 样 的 调用 形式 fffields} 是 一 种 语法 糖 用 于 表 
示 f({fields}) ; 这 里 指 参数 列表 是 一 个 新 创建 出 来 的 列表 。 而 这 样 的 形式 f'_string_， 
(或 是 TEST om 亦 或 是 f[[_string_]] ) 也 是 一 种 语法 糖 ， 用 于 表示 f('_string_') ，; 
此 时 的 参数 列表 是 一 个 单独 的 字符 串 。 


return _functioncal1l 这 样 的 调用 形式 将 触发 一 次 尾 调 用 。 Lua 实现 了 完全 尾 调用 (或 称 
为 完全 尾 递 为 ) : 在 尾 调 用 中 ， 被 调用 的 函数 重用 调用 它 的 函数 的 堆栈 项 。 因此 ， 对 于 程 
序 执行 的 找 套 尾 调 用 的 层 数 是 没有 限制 的 。 然而 ， 尾 调用 将 删除 调用 它 的 画 数 的 任何 调试 信 
息 。 注意 ， 尾 调用 只 发 生 在 特定 的 语法 下 ， 仅 当 return 只 有 单一 男 数 调用 作为 参数 时 才 发 
生 尾 调用 ; 这 种 语法 使 得 调用 画 数 的 所 有 结果 可 以 完整 地 返回 。 因此 ， 下 面 这 些 例子 都 不 是 
尾 调 用 : 





return (f(x)) -- 返回 值 被 调整 为 一 个 
return 2 * f(x) 

return x, f(x) - - 追加 若干 返回 值 
f(x); return - - 返回 值 全 部 被 舍弃 
return x or f(x) - - 返回 值 被 调整 为 一 个 


3.4.11 -- 加 数 定义 
函数 定义 的 语法 如 下 : 


functiondef ::= **function** funcbody 
funcbody ::= ‘**(**’ [parlist] ‘**)**’ block **end** 


另外 定义 了 一 些 语法 糖 简 化 函数 定义 的 写法 : 


Stat ::= **function** funcname funcbody 

Stat ::= **]1ocal** **function** Name funcbody 

funcname ::= Name {**.**’ Name} [‘**:**’ Name] 
该 语句 


function f () _body_ end 


被 转译 成 


f = function () _body_ end 


function t.a.b.c.f () _body_ end 


被 转译 成 


t.a.b.c.f = function () _body_ end 


local function f () _body_ end 


被 转译 成 


local f; f = function () _body_ end 


而 不 是 


local f = function () _body_ end 


《这 个 差别 只 在 函数 体内 需要 引用 f 时 才 有 。) 


一 个 函数 定义 是 一 个 可 执行 的 表达 式 ， 执行 结果 是 一 个 类 型 为 function 的 值 。 当 Lua 预 编 译 
一 个 代码 块 时 ， 代码 块 作为 一 个 画 数 ， 整 个 函数 体 也 就 被 预 编译 了 。 那么 ， 无 论 何 时 Lua 执 
行 函数 定义 ， 这 个 男 数 本 身 就 进行 了 实例 化 (或 者 说 是 关闭 了 ) 。 这 个 函数 的 实例 (或 
者 说 是 闭 包 ) 是 表达 式 的 最 终 值 。 


形 参 被 看 作 是 一 些 局 部 变量 ， 它们 将 由 实 参 的 值 来 初始 化 : 


parla:ste: = name ln le S00 te | 关 全 全 


当 一 个 画 数 被 调用 ， 如 果 函 数 并 非 一 个 可 变 参 数 函 数 ， 即 在 形 参 列表 的 末尾 注 明 三 个 点 

(" ... '")， 那么 实 参 列表 就 会 被 调整 到 形 参 列表 的 长 度 。 变 长 参数 函数 不 会 调整 实 参 列表 ; 
取而代之 的 是 ， 它 将 把 所 有 额外 的 参数 放 在 一 起 通过 变 长 参数 表达 式 传递 给 玉 数 ， 其 写法 依 
旧 是 三 个 点 。 这 个 表达 式 的 值 是 一 串 实 参 值 的 列表 ， 看 起 来 就 跟 一 个 可 以 返回 多 个 结果 的 函 
数 一 样 。 如 果 一 个 变 长 参数 表达 式 放 在 另 一 个 表达 式 中 使 用 ， 或 是 放 在 另 一 串 表 达 式 的 中 
间 ， 那么 它 的 返回 值 就 会 被 调整 为 单个 值 。 若 这 个 表达 式 放 在 了 一 系列 表达 式 的 最 后 一 个 ， 
就 不 会 做 调整 了 (除非 这 最 后 一 个 参数 被 括号 给 括 了 起 来 ) 。 


我 们 先 做 如 下 定义 ， 然 后 再 来 看 一 个 例子 


function f(a, b) end 
function g(a, b, ...) end 
function r() return 1,2,3 end 


下 面 看 看 实 参 到 形 参 数 以 及 可 变 长 参数 的 映射 关系 : 


CALL PARAMETERS 

f(3) a=3, b=nil 

f(3, 4) a=3, b=4 

f(3, 4, 5) a=3, b=4 

f(r(), 10) a=1, b=10 

f(r()) a=1, b=2 

g(3) a=3, b=nil, --> (nothing) 
gl(374) a=3, b=4, --> (nothing) 
g(3, 4, 5, 8) a=30 D4 --> 5 8 
g(5, r()) a=5, b=1, 二 2 3 


结果 由 return 来 返回 (参见 83.3.4) 。 如 果 执 行 到 函数 末尾 依旧 没有 遇 到 任何 return 语 
句 ， 加 数 就 不 会 返回 任何 结果 。 


关于 画 数 可 返回 值 的 数量 限制 和 系统 有 关 。 这 个 限制 一 定 大 于 1000 。 
冒号 语法 可 以 用 来 定义 方法 ， 就 是 说 ， 画 数 可 以 有 一 个 隐 式 的 形 参 self 。 因此 ， 如 下 语 


是 


function t.a.b.c:f (_params_ ) _body_ end 





是 这 样 一 种 写法 的 语法 糖 





t.a.b.c.f = function (self, _params_) _body_ end 


3.5 一 可见 性 规则 


Lua 语言 有 词法 作用 范围 。 ad 语句 段 ， 结束 于 包 
这 个 声明 的 最 内 层 语 句 块 的 最 后 一 个 非 空 语句 。 看 下 面 这 些 例子 


x = 10 - 全 局 变量 


do - 新 的 语句 块 
local x = x - 新 的 一 个 'x'， 它 的 值 现在 是 10 
print(x) -> 10 
X = x+1 
do 另 一 个 语句 块 
local x = x+1 A Se 
print(x) --> 12 
end 
print(x) --> 11 
end 
print (x) --> 10 ( 取 到 的 是 全 局 的 那 一 个 ) 


注意 这 里 ， 类 似 local x = x 这 样 的 声明 ， 新 的 x 正在 被 声明 ， 但 是 还 没有 进入 它 的 作用 
范围 ， 所 以 第 二 个 x 指向 的 是 外 面 一 层 的 变量 。 


因为 有 这 样 一 个 词法 作用 范围 的 规则 ， 局 部 变量 可 以 被 在 它 的 作用 范围 内 定义 的 函数 自由 使 
用 。 当 一 个 局 部 变量 被 内 层 的 函数 中 使 用 的 时 候 ， 它 被 内 层 酌 数 称 作 上 值 ， 或 是 外 部 局 部 


注意 ， 每 次 执行 到 一 个 local 语句 都 会 定义 出 一 个 新 的 局 部 变量 。 看 看 这 样 一 个 例子 : 


a 名 
Jocal x = 20 
for i=1,10 do 


local y = 0 
a[i] = function () y=y+1; return x+y end 
end 


这 个 循环 创建 了 十 个 闭 包 〈 这 指 十 个 匿名 函数 的 实例 ) 。 这 些 闭 包 中 的 每 一 个 都 使 用 了 不 同 
的 y 变量 ， 而 它们 又 共享 了 同一 份 x 。 


4- 编程 接口 


这 个 部 分 描述 了 Lua 的 C API ， 也 就 是 宿主 程序 跟 Lua 通讯 用 的 一 组 C 男 数 。 所 有 的 API 
函数 按 相 关 的 类 型 以 及 常量 都 声明 在 头 文件 1ua.n 中 。 


虽然 我 们 说 的 是 “ 画 数 ”， 但 一 部 分 简单 的 API 是 以 宏 的 形式 提供 的 。 除非 另 有 说 明 ， 所 有 的 
这 些 宏 都 只 使 用 它们 的 参数 一 次 (除了 第 一 个 参数 ， 那 一 定 是 Lua 状态 ) ， 因此 你 不 需 担 心 
这 些 宏 的 展开 会 引起 一 些 副作用 。 


C 库 中 所 有 的 Lua API 函数 都 不 去 检查 参数 是 否 相 容 及 有 效 。 然而 ， 你 可 以 在 编译 Lua 时 加 
上 打开 一 个 宏 开 关 LuA_UsE_APICHECK 来 改变 这 个 行为 。 


4.1 一 材 


Lua 使 用 一 个 虚拟 栈 来 和 C 互 传 值 。 栈 上 的 的 每 个 元 素 都 是 一 个 Lua 值 (nil， 数 字 ， 字 符 
串 ， 等 等 ) 。 


无 论 何 时 Lua 调用 C， 被 调用 的 函数 都 得 到 一 个 新 的 栈 ， 个 栈 独 立 于 C 函数 本 身 的 栈 ， 也 
独立 于 之 前 的 Lua 栈 。 它 里 面包 含 了 Lua 传递 给 C 0 而 C 画 数 则 把 要 返回 
的 结果 放 入 这 个 栈 以 返回 给 调用 者 (参见 lua_cFunction ) 。 


方便 起 见 ， 所 有 针对 栈 的 API 查询 操作 都 不 严格 遵循 栈 的 操作 规则 。 而 是 可 以 用 一 个 索引 
来 指向 栈 上 的 任何 元 素 : 正 的 索引 指 的 是 栈 上 的 绝对 位 置 (从 1 开始 ) ; 负 的 索引 则 指 从 栈 
项 开始 的 偏 移 量 。 展开 来 说 ， a 那么 索引 1 es (也 就 是 
最 先 被 压 栈 的 元 素 ) 而 索引 n 则 指 最 后 一 个 元 素 ; 索引 -1 也 是 指 最 后 一 个 元 素 〈 即 栈 顶 的 
元 素 ) ， 索引 -n 是 指 第 一 人 个 元 素 。 


4.2 一 栈 大 小 


当 你 使 用 Lua API 时 ， 就 有 责任 保证 做 恰当 的 调用 。 特别 需要 注意 的 是 ， 你 有 责任 控制 不 
要 堆栈 浴 出 。 你 可 以 使 用 lua_checkstack 这 个 图 数 来 扩大 可 用 堆栈 的 尺寸 。 


无 论 何 时 Lua 调用 C ， 它 都 只 保证 至 少 有 LuA_MINSTACK 这 么 多 的 堆栈 空间 可 以 使 用 。 
LUA_MINSTACK 一 般 被 定义 为 20 ， 因此， 只 要 你 不 是 不 断 的 把 数据 压 栈 ， 通常 你 不 用 关心 堆 
栈 大 小 。 


当 你 调用 一 个 Lua 画 数 却 没有 指定 要 接收 多 少 个 返回 值 时 (参见 lua_call ) ， Lua 可 以 保 
证 栈 一 定 有 足够 的 空间 来 接收 所 有 的 返回 值 ， 但 不 保证 此 外 留 有 额外 的 空间 。 因此 ， 在 做 了 
一 次 这 样 的 调用 后 ， 如 果 你 需要 继续 压 栈 ， 则 需要 使 用 1lua_checkstack 。 


4.3 - 有 效 素 引 与 可 接受 索引 


API 中 的 函数 若 需 要 传 入 栈 索 引 ， 这 个 索引 必须 是 有 效 索 引 或 是 可 接受 索引 。 


有 效 索 引 指引 用 栈 内 真实 位 置 的 索引 ; 即 在 1 到 栈 顶 之 间 的 位 置 
( 1 < abs(index) < top ) o 通常 ， 一 个 可 能 修改 该 位 置 的 值 的 函数 需要 传人 有 效 索 引 。 


除非 另 有 说 明 ， 任何 可 以 接受 有 效 素 引 的 函数 同时 也 接受 伪 索 引 。 伪 索 引 指 代 一 些 可 以 被 C 
code 访问 得 到 Lua 值 ， 而 它们 又 不 在 栈 内 。 这 用 于 访问 注册 表 以 及 C 函数 的 上 值 (参见 
§4.4) 。 


对 于 那些 只 是 需要 栈 中 的 值 ( 例 如 查询 函数 ) 而 不 需要 指定 一 个 栈 位 置 的 范 数 ， 可 以 用 一 
可 接受 的 索引 去 调用 它们 。 可 接受 索引 不 仅 可 以 是 任何 包括 伪 索 引 在 内 的 有 效 索 引 ， i 
是 任何 超过 栈 项 但 落 在 为 栈 分 配 出 来 的 空间 内 的 正 索 引 。 (注意 0 永远 都 不 是 一 个 可 接受 束 
引 。) 除非 另 有 说 明 ，API 里 的 函数 都 接受 可 接受 素 引 。 


允许 可 接受 索引 是 为 了 避免 对 栈 顶 以 外 的 查询 时 做 额外 的 检查 。 例如 ，C 本 数 可 以 直接 查询 
传 给 它 的 第 三 个 参数 ， 而 不 用 先 检查 是 不 是 有 第 三 个 参数 ， 即 不 需要 检查 3 是 不 是 一 个 有 效 
索引 。 


对 于 那些 以 可 接受 索引 调用 的 函数， 无效 索引 被 看 作 包 含 了 一 个 虚拟 类 型 LuA_TNONE 的 值 ， 
这 个 值 的 行为 和 nil 一 致 。 


4.4 一 C 闭 包 


C 沙 数 被 创建 出 来 ， 我 们 有 可 能 会 把 一 些 值 关联 在 一 起 ， 也 就 是 创建 一 个 C 闭 包 (参见 
lua_pushcclosure ) ; 这 些 被 关联 起 来 的 值 被 叫做 上 值 ， 它们 可 以 在 图 数 被 调用 的 时 候 访 
问 的 到 。 


论 何 时 去 调用 C 函数 ， 画 数 的 上 值 都 可 以 用 伪 索 引 定 位 。 我 们 可 以 用 lua_upvalueindex 
这 个 宏 来 生成 这 些 伪 索引 。 第 一 个 关联 到 辑 数 的 值 放 在 lua_upvalueindex(1) 位 置 处 ， 依 此 
类 推 。 使 用 1ua_upvalueindex(_n_) 时 ， 若 n 大 于 当前 函数 的 总 上 值 个 数 (但 不 可 以 大 于 
256) 会 产生 一 个 可 接受 的 但 无 效 的 索引 。 


注册 表 


Lua 提供 了 一 个 注册 表 ， 这 是 一 个 预定 义 出 来 的 表 ， 可 以 用 来 保存 任何 C 代码 想 保 存 的 
Lua 值 。 这 个 表 可 以 用 有 效 伪 索引 LUA_REGISTRYINDEX 来 定位 。 任何 C 库 都 可 以 在 这 张 表 里 
保存 数据 ， 为 了 防止 冲突 ， 你 需要 特别 小 心 的 选择 键 名 。 一 般 的 用 法 是 ， 你 可 以 用 一 个 包含 
你 的 库 名 的 字符 串 做 为 键 名 ， 或 者 取 你 自己 C 对 象 的 地 址 ， 以 轻 量 用 户 数据 的 形式 做 键 ， 还 
可 以 用 你 的 代码 创建 出 来 的 任意 Lua 对 象 做 键 。 关于 变量 名 ， 字 符 串 键 名 中 以 下 划 线 加 大 写 
字母 的 名 字 被 Lua 保留 。 


注册 表 中 的 整数 键 用 于 引用 机 制 (参见 lualL_ref ) ， 以 及 一 些 预定 义 的 值 。 因此 ， 整 数 键 
不 要 用 于 别 的 目的 。 

当 你 创建 了 一 个 新 的 Lua 状态 机 ， 其 中 的 注册 表 内 就 预定 义 好 了 几 个 值 。 这 些 预定 义 值 可 以 
用 整数 索引 到 ， 这 些 整数 以 常数 形式 定义 在 lua.n 中 。 有 下 列 常数 : 


e。 LUA_RIDX_MAINTHREAD : 注册 表 中 这 个 索引 下 是 状态 机 的 主线 程 。 (主线 程 和 状态 机 同时 
被 创建 出 来 。 ) 
e。 LUA_RIDX_GLOBALS : 注册 表 的 这 个 索引 下 是 全 局 环境 。 


4.6 - C 中 的 错误 义理 


在 内 部 实现 中 ， Lua 使 用 了 C 的 longjmp 机 制 来 处 理 错 错误 。 (如 果 你 使 用 C++ 编译 ，Lua 
将 换 成 异常 ; 细节 请 在 源 代 码 中 搜索 LuAIi_THRow 。) 当 Lua 磋 到 任何 错误 (比如 内 存 分 配 
错误 、 类 型 错误 、 语 法 错误 、 还 有 运行 时 错误 ) 它 都 会 抛 出 一 个 错误 出 去 ; 也 就 是 调用 一 次 


长 跳 转 。 在 保护 环境 下 ， Lua 使 用 setjmp ey 任何 发 生 的 错误 都 会 跳 转 
到 最 近 的 一 个 恢复 点 。 


如 果 错误 发 生 在 保 扩 环境 之 外 ， Lua 会 先 调 用 panic 内 本 数 (参见 lua_atpanic ) 然后 调用 
abort 来 退出 宿主 程序 。 你 的 panic 本 数 只 要 不 返回 (例如 : 长 跳 转 到 你 在 Lua 外 你 自己 
设置 的 恢复 点 ) 就 可 以 不 退出 程序 。 


panic 函数 以 错误 消息 处 理 器 (参见 $2.3) 的 方式 运行 ; 错误 消息 在 栈 顶 。 不 同 的 是 ， 它 不 
保证 栈 空间 。 做 任何 压 栈 操作 前 ，panic 函数 都 必须 先 检 查 是 否 有 足够 的 空间 (参见 
S4.2) 。 


大 多 数 API 画 数 都 有 可 能 抛 出 错误 ， 例如 在 内 存 分 配 错 误 时 就 会 抛 出 。 每 个 函数 的 文档 都 会 
注 明 它 是 否 可 能 抛 出 错误 。 


函数 内 部 ， 你 可 以 通过 调用 1ua_error 来 抛 出 错误 。 


4.7 - C 中 的 让 出 处 理 


Lua 内 部 使 用 C 的 longjmp 机 制 让 出 一 个 协 程 。 因此 ， 如 果 一 个 C 函数 foo 调用 了 一 
API 函数 ， 而 这 个 API 本 数 让 出 了 (直接 或 间接 调用 了 让 出 函数 ) 。 由 于 1longjmp 会 移 除 
C 栈 的 栈 帧 ， Lua 就 无 法 返回 到 foo 里 了 。 


为 了 回避 这 类 问题 ， 碰 到 API 调用 中 调用 让 出 时 ， 除 了 那些 抛 出 错误 的 API 外 ， 还 提供 了 三 
个 函数 : lua yieldk ， lua_callk ， 和 lua pcallk 。 它们 在 让 出 发 生 时 ， 可 以 从 传人 的 
延续 范 数 (名 为 k 的 参数 ) 继续 运行 。 


我 们 需要 预 设 一 些 术 语 来 解释 延续 点 。 对 于 从 Lua 中 调用 的 C 画 数 ， 我 们 称 之 为 原画 数 。 
从 这 个 原 玫 数 中 调用 的 上 面 所 述 的 三 个 C API 函数 我 们 称 之 为 被 调 函 数 。 被 调 男 数 可 以 使 当 
前 线程 让 出 。 (让 出 发 生 在 被 调 画 数 是 lua yieldk ， 或 传人 lua callk 或 lua pcallk 的 
函数 调用 了 让 出 时 。) 


假设 正在 运行 的 线程 在 执行 被 调 范 数 时 让 出 。 当 再 次 延续 这 条 线程 ， 它 希望 继续 被 调 函 数 的 
运行 。 然而 ， 被 调 酌 数 不 可 能 返回 到 原 函 数 中 。 a 作 破 坏 了 C 栈 的 栈 
帧 。 作为 替代 品 ，Lua 调用 那个 作为 被 调 琅 数 人 参数 给 出 的 延续 男 数 。 正如 其 名 ， 延 续 函 数 
将 延续 原 图 数 的 任务 。 


下 面 的 画 数 会 做 一 个 说 明 : 


int original function (Lua_State *L) { 
: /code® ey 
status = lua pcall(L, n, m, h); /* calls Lua */ 
。 /* code 2 */ 


现在 我 们 想 人 允许 引 lua_pcall 运行 的 Lua 代码 让 出 。 首先 ， 我 们 把 画 数 改写 成 这 个 样子 : 


int k (lua_ State *L, int status, lua KContext ctx) { 
/code 2 

} 

int original function (lua_ State *L) { 


COOUEEET 
return k(L, lua pcall(L, n, m, h), ctx); 


上 面 的 代码 中 ， 新 函数 k 就 是 一 个 延续 函数 ( 辑 数 类 型 为 lua_kFunction ) 。 它 的 工作 就 
是 原 函 数 中 调用 lua_pcall 之 后 做 的 那些 事情 。 现在 我 们 必须 通知 Lua 说 ， 你 必须 在 被 
lua_pcall 执行 的 Lua 代码 发 生 过 中 断 (错误 或 让 出 ) 后 ， 还 得 继续 调用 k 。 所 以 我 们 还 
得 继续 改写 这 段 代 码 ， 把 1ua pcall 替换 成 lua pcallk : 


int original function (lua_ State *L) { 
Code 下] 本/ 
return k(L, lua pcallk(L, n, m, h, ctx2, k), ctx1); 


注意 这 里 那个 额外 的 显 式 的 对 延续 画 数 的 调用 : Lua 人 私 在 需要 时 ， 这 可 能 是 由 错误 导致 的 也 
可 能 是 发 生 了 让 出 而 需要 继续 运行 ， 才 会 调用 延续 落 数 。 如 果 没 有 发 生 过 任何 让 出 ， 调 用 的 
责 数 正常 返回 ， 那么 1ua _pcallk (以 及 lua _callk ) 也 会 正常 返回 。 (当然 ， 这 个 例子 中 
你 也 可 以 不 在 之 后 调用 延续 男 数 ， 而 是 在 原 函 数 的 调用 后 直接 写 上 需要 做 的 工作 。) 


除了 Lua 状态 ， 延 续 函 数 还 有 两 个 参数 : 一 个 是 调用 最 后 的 状态 码 ， 另 一 个 一 开始 由 
lua_pcallk 传人 的 上 下 文 ( ctx ) o (Lua 本 身 不 使 用 这 文 个 值 ; ; 它 久 仅 从 原 函 数 转发 这 个 
值 给 延续 本 数 。) 对 于 1lua_pcallk 而 襄 ， 状态 码 和 1lua_pcallk 本 应 返回 值 相同 ， 区 别 仅 
在 于 发 生 过 让 出 后 才 执 行 完 时 ， 状 态 码 为 LUA_YIELD (而 不 是 LuA_ok ) 。 对 于 


lua_yieldk 和 lua_callk 而 言 ， 调用 延续 函数 传人 的 状态 码 一 定 是 LUA YIELD 。 (对 这 两 
个 函数 ，Lua 不 会 因 任 何 错误 而 调用 延续 函数 。 因为 它们 并 不 义理 错误 。) 同样 ， 当 你 使 用 
lua_callk 时 ， 你 应 该 用 LuA ok 作为 状态 码 来 调用 延续 图 数 。 (对 于 1lua_yieldk ， 几乎 
没有 什么 地 方 需要 直接 调用 延续 函数 ， 因为 lua_yieldk 本 身 并 不 会 返回 。) 


Lua 会 把 延续 函数 看 作 原 范 数 。 延续 函数 将 接收 到 和 原画 数 相同 的 Lua 栈 ， 其 接收 到 的 lua 
状态 也 和 被 调 画 数 若 返回 后 应 该 有 的 状态 一 致 。 (例如 ， 1lua_callk 调用 之 后 ， 栈 中 之 前 
压 入 的 函数 和 调用 参数 都 被 调用 产生 的 返回 值 所 替代 。) 这 时 也 有 相同 的 上 值 。 等 到 它 返 回 
的 时 候 ，Lua 会 将 其 看 待 成 原画 数 的 返回 去 操作 。 


_ 画 数 和 类 型 


这 里 按 字母 次 序列 出 了 所 有 C API 中 的 函数 和 类 型 。 每 个 本 数 都 有 一 个 这 样 的 提示 : [-o, +p， 


bd 


对 于 第 一 个 域 ，。， 指 的 是 该 函数 会 从 栈 上 弹出 多 少 个 元 素 。 第 二 个 域 ， p ， 指 该 函数 会 
将 多 少 个 元 素 压 栈 。 (所 有 函数 都 会 在 弹出 参数 后 再 把 结果 压 栈 。) ”xly 这 种 形式 的 域 表 
示 该 图 数 根据 县 体 情况 可 能 斑 入 (或 弹出 ) x 或 y 个 元 素 ; 问号 ' ?' 表示 我 们 无 法 仅 通 
过 参数 来 了 解 该 图 数 会 弹出 / 太 入 多 少 元 素 be 数量 取决 于 栈 上 有 些 什么 ) 。 第 三 个 
域 ， x ， 解释 了 该 落 数 是 否 会 抛 出 错误 : ' 表示 该 玉 数 绝对 不 会 抛 出 错误 ; ' e ' 表示 该 
函数 可 能 抛 出 错误 ; ' v' 表示 该 玉 数 可 外 E 抛 出 有 意 久 的 错误 。 


lua absindex 
[-0， +0， 一 | 


int lua absindex (Jua_State *L, int idx); 


将 一 个 可 接受 的 索引 idx 转换 为 绝对 索引 ( 即 ， 一 个 不 依赖 栈 顶 在 哪 的 值 ) 。 
lua Alloc 


typedef void * (*lua Alloc) (void *ud, 
void *ptr, 
size_t osize, 
size_t nsize); 


Lua 状态 机 中 使 用 的 内 存 分 配器 函数 的 类 型 。 内 存 分 配 画 数 必须 提供 一 个 功能 类 似 于 
realloc 但 又 不 完全 相同 的 函数 。 它 的 参数 有 ud ， 一 个 由 lua_newstate 传 给 它 的 指针 ; 
ptr ， 一 个 指向 已 分 配 出 来 /将 被 重新 分 配 /要 释放 的 内 存 块 指针 ; osize ， 内 存 块 原来 的 尺 
寸 或 是 关于 什么 将 被 分 配 出 来 的 代码 ; nsize ， 新 内 存 块 的 尺寸 。 


如 果 ptr 不 是 NuULL ， osize 是 ptr 指向 的 内 存 块 的 尺寸 ， 即 这 个 内 存 块 当初 被 分 配 或 
重 分 配 的 尺寸 。 


如 果 ptr 是 NULL ， osize 是 Lua 即将 分 配对 象 类 型 的 编码 。 当 ( 且 仅 当 ) Lua 创建 一 个 
对 应 类 型 的 新 对 象 时 ， osize 是 LUA TSTRING ， LUA TTABLE ， LUA TFUNCTION ， 
LUA_TUSERDATA ， 或 LUA_TTHREAD 中 的 一 个 。 若 osize 是 其 它 类 型 ，Lua 将 为 其 它 东 西 分 


配 内 存 。 
Lua 假定 分 配器 范 数 会 遵循 以 下 行为 : 
当 nsize 是 需 时 ， 分 配器 必须 和 free 行为 类 似 并 返回 NULL 。 


当 nsize 不 是 霉 时 ， 分 配器 必须 和 realloc 行为 类 似 。 如 果 分 配器 无 法 完成 请 求 ， 返 回 
NULL 。 Lua 假定 在 osize &gt;= nsize 成 立 的 条 件 下 ， 分 配器 绝 不 会 失败 。 


这 里 有 一 个 简单 的 分 配器 函数 的 实现 。 这 个 实现 被 放 在 补充 库 中 ， 供 LUaL_newstate 使 用 。 


static void *]_ alloc (void *ud, void *ptr, size_t osize, 
size t nsize) { 
(void)ud; (void)osize; /* not used */ 
if (nsize == 0) { 
free(ptr); 
return NULL ， 


else 
return realloc(ptr, nsize); 


} 


注意 ， 标准 C 能 确保 free(NULL) 没有 副作用 ， 且 realloc(NULL, size) 等 价 于 
malloc(size) 。 这 段 代 码 假定 realloc 在 缩小 块 长 度 时 不 会 失败 。 (虽然 标准 C 没有 对 此 
行为 做 出 保证 ， 但 这 看 起 来 是 一 个 安全 的 假定 。) 


lua arith 
[-(2|1), +1, e] 


void lua arith (lua State *L, int op); 


对 栈 顶 的 两 个 值 (或 者 一 个 ， 上 比如 取 反 ) 做 一 次 数学 或 位 操作 。 其 中 ， 栈 项 的 那个 值 是 第 二 
个 操作 数 。 它 会 弹出 压 入 的 值 ， 并 把 结果 放 在 栈 项 。 这 个 豆 数 遵循 Lua 对 应 的 操作 符 运算 规 
则 ( 即 有 可 能 触发 元 方法 ) 。 


op 的 值 必 须 是 下 列 常量 中 的 一 个 : 
。 LUA_oPADD : 加 法 (+) 

e。 LUA OPSUB :减法 (-) 

。 LUA_oPMUL : 乘法 (*) 

。 LUA_oPDIV : 浮 点 除法 ( / ) 


。 LUA_oPIDIV : 向 下 取 整 的 除法 ( // ) 
e。 LUA_oPMoD : 取 模 ( % ) 

e。 LUA_oPPOW : 乘 方 (^) 

e LUA_OPUNM : 取 负 (一 元 - ) 

e ”LUA_OPBNOT : 按 位 取 反 ( ~ ) 

e。 LUA_oPBAND : 按 位 与 (& ) 

e。 LUA_oPBOR : 按 位 或 ( | ) 

e。 LUA_oPBXxoR : 按 位 异 或 ( ~ ) 

。 LUA_OPSHL : 左 移 ( &lti&lt; ) 


e。 LUA_oPSHR : 右 移 ( &gt;&gt; ) 


lua_atpanic 
[-0， +0， 一 | 


lua_CFunction lua atpanic (lua_ State *L, lua CFunction panicf); 


设置 一 个 新 的 panic 函数 ， 并 返回 之 前 设置 的 那个 。 (参见 $S4.6) 。 


lua call 
[-(nargs+1), +nresults, e] 


void Jua call (lua State *L, int nargs, int nresults); 


调用 一 个 函数 。 


要 调用 一 个 函数 请 遵循 以 下 协议 : 首先 ， 要 调用 的 函数 应 该 被 压 人 栈 ; 接着 ， 把 需要 传递 给 
这 个 画 数 的 参数 按 正 序 压 栈 ; 这 是 指 第 一 个 参数 首先 压 栈 。 最 后 调用 一 下 1ua call ; 
nargs 是 你 压 人 栈 的 参数 个 数 。 当 画 数 调用 完毕 后 ， 所 有 的 参数 以 及 函数 本 身 都 会 出 栈 。 
而 函数 的 返回 值 这 时 则 被 压 栈 。 返回 值 的 个 数 将 被 调整 为 nresults 个 ， 除非 nresults 被 
设置 成 LuA_MuLTRET 。 在 这 种 情况 下 ， 所 有 的 返回 值 都 被 压 人 堆栈 中 。 Lua 会 保证 返回 值 都 
Ta 函数 返回 值 将 按 正 序 压 栈 〈 第 一 个 返回 值 首先 压 栈 ) ， 因此 在 调用 结束 后 ， 
最 后 一 个 返回 值 将 被 放 在 栈 顶 。 


被 调用 函数 内 发 生 的 错误 将 (通过 longjmp ) 一 直上 抛 。 
下 面 的 例子 中 ， 这 行 Lua 代码 等 价 于 在 宿主 程序 中 用 C 代码 做 一 些 工作 : 


a = f("how", t.x, 14) 


这 里 是 C 里 的 代码 : 


Jua_getglobal(L, "f"); /* function to be called */ 


Jua_pushliteral(L, "how"); /* 1st argument */ 
Jua_getglobal(L, "t"); /* table to be indexed */ 
Jua_getfield(L, -1, "x"); /* push result of t.x (2nd arg) */ 
Jua_remove(L, -2); /* remove 't' from the stack */ 
lua_pushinteger(L, 14); /* 3rd argument */ 
Luancall(E 33> 0 /* call 'f' with 3 arguments and 1 result */ 
Jua_setglobal(L, "a"); /* set global 'a' */ 


注意 上 面 这 段 代 码 是 平衡 的 : 到 了 最 后 ， 堆 栈 恢复 成 原 有 的 配置 。 这 是 一 种 良好 的 编程 习 


= 


lua_ callk 
[-(nargs + 1), +nresults, e] 


void lua callk (lua State *L, 
int nargs, 
int nresults, 
Jua KContext ctx, 
lua_KFunction k); 


这 个 画 数 的 行为 和 1lua_call 完全 一 致 ， 只 不 过 它 还 人 允许 被 调用 的 函数 让 出 (参见 S4.7) 。 
lJua CFunction 


typedef int (*]lua CFunction) (lua_ State *L); 


C 本 数 的 类 型 。 


为 了 正确 的 和 Lua 通讯 ， C 函数 必须 使 用 下 列 协议 。 这 个 协议 定义 了 参数 以 及 返回 值 传 递 方 
法 : C 画 数 通 过 Lua 中 的 栈 来 接受 参数 ， 参数 以 正 序 人 栈 (第 一 个 参数 首先 入 栈 ) 。 因 
此 ， 当 画 数 开始 的 时 候 ， lua_gettop(L) 可 以 返回 函数 收 到 的 参数 个 数 。 第 一 个 参数 (如果 
有 的 话 ) 在 索引 1 的 地 方 ， 而 最 后 一 个 参数 在 索引 lua_gettop(L) 人 处。 当 需 要 向 Lua 返回 
值 的 时 候 ， C 画 数 只 需要 把 它们 以 正 序 压 到 堆栈 上 【第 一 个 返回 值 最 先 压 人 ) ， 然后 返回 这 
些 返 回 值 的 个 数 。 在 这 些 返 回 值 之 下 的 ， 堆 栈 上 的 东西 都 会 被 Lua 丢掉 。 和 Lua 加 数 一 
样 ， 从 Lua 中 调用 C 画 数 也 可 以 有 很 多 返回 值 。 


下 面 这 个 例子 中 的 函数 将 接收 若干 数字 参数 ， 并 返回 它们 的 平均 数 与 和 : 


static int foo (Lua_State *L) 


int n = lua_gettop(L); A/* 参数 的 个 数 *7y 
Jua Number sum = 0.0; 
int i; 


ROG GE = nr 
if (!lua isnumber(L, i)) { 
lua_pushliteral(L, "incorrect argument"); 
lua_error(L); 


Sum += Jua_tonumber(L, i); 


} 

lua_pushnumber (L, sum/n); /* 第 一 个 返回 值 */ 
1Lua_pushnumber(L，sum) ， /* 第 二 个 返回 值 */ 
return 2; /* 返回 值 的 个 数 */ 


lua_ checkstack 
[-0， +0， - 
int lua_ checkstack (lua_ State *L, int n); 
确保 堆栈 上 至 少 有 nm 个 额外 空位 。 如 果 不 能 把 堆栈 扩展 到 相应 的 尺寸 ， 男 数 返 回 假 。 失败 


的 原因 包括 将 把 栈 扩展 到 比 固定 最 大 尺寸 还 大 (至 少 是 几 千 个 元 素 ) 或 分 配 内 存 失败 。 这 个 
画 数 永 远 不 会 缩小 堆栈 ; 如 果 堆 栈 已 经 比 需要 的 大 了 ， 那 么 就 保持 原样 。 


lua close 
[-0， +0， 一 | 


void Jua close (lua State *L); 


销毁 指定 Lua 状态 机 中 的 所 有 对 象 (如 果 有 垃圾 收集 相关 的 元 方法 的 话 ， 会 调用 它们 ) ， 并 
且 释 放 状 态 机 中 使 用 的 所 有 动态 内 存 。 在 一 些 平台 上 ， 你 可 以 不 必 调 用 这 个 函数 ， 因为 当 宿 
主 程序 结束 的 时 候 ， 所 有 的 资源 就 自然 被 释放 掉 了 。 另 一 方面 ， 长 期 运行 的 程序 ， 上 比如 一 个 
后 台 程序 或 是 一 个 网 站 服务 器 ， 会 创建 出 多 个 Lua 状态 机 。 那 么 就 应 该 在 不 需要 时 赶紧 关闭 
它们 。 


lua_ compare 
[-0, +0, e] 


int lua compare (lua_ State *L, int index1, int index2, int op); 


比较 两 个 Lua 值 。 当 索 引 index1 处 的 值 通 过 op 和 索引 index2 处 的 值 做 比较 后 条 件 满 
足 ， 画 数 返 回 1 。 这 个 画 数 遵循 Lua 对 应 的 操作 规则 〈 即 有 可 能 触发 元 方法 ) 。 反之 ， 图 数 
返回 0。 当 任 何 一 个 索引 无 效 时 ， 男 数 也 会 返回 0 。 


op 值 必须 是 下 列 常量 中 的 一 个 : 
。 LUA_oPEQ : 相等 比较 ( == ) 


e LUA_oPLT : 小 于 比较 ( &lt; ) 
e。 ”LUA_OPLE : 小 于 等 于 比较 ( &lt;= ) 


lua concat 
[-n, +1, e] 


void Jua concat (lua_ State *L, int n); 


连接 栈 顶 的 n 个 值 ， 然后 将 这 些 值 出 栈 ， 并 把 结果 放 在 栈 顶 。 如 果 n 为 1， 结果 就 是 那 
个 值 放 在 栈 上 ( 即 ， 画 数 什 么 都 不 做 ) ; 如 果 n 为 0 ， 结 果 是 一 个 空 串 。 连接 依照 Lua 中 
通常 语义 完成 (参见 S3.4.6 ) 。 


lua_ copy 
[-0， +0， 加 | 


void lua copy (Lua_State *L, int fromidx, int toidx); 


从 索引 fromidx 义 复制 一 个 值 到 一 个 有 效 索 引 toidx 多 ， 履 盖 那 里 的 原 有 值 。 不 会 影响 其 
它 位 置 的 值 。 


lua createtable 
[-0, +1, e] 


void lJua createtable (lua State *L, int narr, int nrec); 


创建 一 张 新 的 空 表 压 栈 。 参数 narr 建议 了 这 张 表 作为 序列 使 用 时 会 有 多 少 个 元 素 ; 参数 
nrec 建议 了 这 张 表 可 能 拥有 多 少 序列 之 外 的 元 素 。 Lua 会 使 用 这 些 建议 来 预 分 配 这 张 新 
表 。 如 果 你 知道 这 张 表 用 途 的 更 多 信息 ， 预 分 配 可 以 提高 性 能 。 否则 ， 你 可 以 使 用 画 数 


Jua_ newtable 。 


lua_dump 


[-0, +0, e] 


int Jua_dump (lua_State *L， 
Jua Writer writer， 
void *data, 
int strip); 


把 函数 导出 成 二 进 制 代 码 块 。 男 数 接收 栈 顶 的 Lua 函数 做 参数 ， 然后 生成 它 的 二 进 制 代 码 


块 。 若 被 导出 的 东西 被 再 次 加 载 ， 加 载 的 结果 就 相当 于 原来 的 函 


条 数 。 当 它 在 产生 代码 块 的 时 


候 ， lua_dump 通过 调用 辑 数 writer (参见 lua writer ) 来 写 人 数据， 后 面 的 data 参 


数 会 被 传人 writer 。 
如 果 strip 为 真 ， 二 进 制 代码 块 将 不 包含 该 范 数 的 调试 信息 。 


最 后 一 次 由 writer 的 返回 值 季 作为 这 个 函数 的 返回 值 返回 ; 0 表示 没有 错误 。 


函数 不 会 把 Lua 画 数 弹出 堆栈 。 


lJua error 
[-1, +0, V] 


int lua_error (lua_ State *L); 


以 栈 顶 的 值 作为 错误 对 象 ， 抛 出 一 个 Lua 错误 。 这 个 图 数 将 做 一 


回 (参见 lJual_error ) o 


lua_gc 
[-0, +0, e] 


int lua gc (lua State *L, int what, int data); 


控制 垃圾 收集 器 。 
本 数 根据 其 参数 whnat 发 起 几 种 不 同 的 任务 : 


e LUA_GCSTOP : 停止 垃圾 收集 器 。 
e LUA_GCRESTART : 重启 垃圾 收集 器 。 
e。 LUA_GCCOLLECT : 发 起 一 次 完整 的 垃圾 收集 循环 。 


次 长 跳 转 ， 所 以 一 定 不 会 返 


。 LUA_6ccouNT : 返回 Lua 使 用 的 内 存 总 量 (以 K 字 节 为 单位 ) 。 


e。 LUA_6ccouNTB : 返回 当前 内 存 使 用 量 除 以 1024 的 余数 。 
e LUA_6CSTEP : 发 起 一 步 增 量 垃圾 收集 。 


e LUA_GCSETPAUSE :把 data 设 为 垃圾 收集 器 间歇 率 (参见 $2.5) ， 并 返回 之 前 设置 的 


值 。 


e LUA_GCSETSTEPMUL :把 data 设 为 垃圾 收集 器 步 进 倍率 (参见 $2.5) ， 并 返回 之 前 设置 


的 值 。 
e ”LUA_6GCISRUNNING : 返回 收集 器 是 否 在 运行 〈 即 没有 停止 ) 。 


关于 这 些 选项 的 细节 ， 参 见 collectgarbage 。 
lua getallocf 
[-0, +0, 一 ] 


lua_Alloc lua getallocf (lua State *L, void **ud); 


返回 给 定 状 态 机 的 内 存 分 配器 画 数 。 如 果 ud 不 是 NULL ， Lua 把 设置 内 存 分 配 男 数 时 设 
置 的 那个 指针 置信 *ud o 


lua getfield 
[-0, +1, e] 


int lua getfield (lua State *L, int index, const char *k); 


把 t[k] 的 值 压 栈 ， 这 里 的 t 是 索引 指向 的 值 。 在 Lua 中 ， 这 个 函数 可 能 触发 对 应 
"index" 事件 对 应 的 元 方法 (参见 $2.4) 。 

函数 将 返回 压 人 值 的 类 型 。 

lua_getextraspace 


[-0， +0， 


void *]lua_getextraspace (lua_ State *L); 


返回 一 个 Lua 状态 机 中 关联 的 内 存 块 指针 。 程序 可 以 把 这 块 内 存 用 于 任何 用 途 ; 而 Lua 不 会 
使 用 它 。 
每 一 个 新 线程 都 会 携带 一 块 内 存 ， 初始 化 为 主线 程 的 这 块 内 存 的 副本 。 


默认 配置 下 ， 这 块 内 存 的 大 小 为 空 指针 的 大 小 。 不 过 你 可 以 重新 编译 Lua 设 定 这 块 内 存 不 同 
的 大 小 。 (参见 luaconf.h 中 的 LUA EXTRASPACE 。) 


lua_ getglobal 
[-0, +1, e] 


int lua getglobal (lua_ State *L, const char *name); 


把 全 局 变量 <name>name</name> 里 的 值 压 栈 ， 返 回 该 值 的 类 型 。 
lua geti 
[-0, +1, e] 


int lua geti (lua State *L, int index, lua_Integer i); 


把 tri] 的 值 压 栈 ， 这 里 的 t 指 给 定 的 索引 指 代 的 值 。 和 在 Lua 里 一 样 ， 这 个 函数 可 能 会 
触发 "index" 事件 的 元 方法 (参见 §2.4) 。 


返回 压 人 值 的 类 型 。 
lua getmetatable 
[-0, +(0|1), 一 


int lua getmetatable (lua State *L, int index); 


如 果 该 索引 处 的 值 有 元 表 ， 则 将 其 元 表 太 栈 ， 返 回 1 。 否则 不 会 将 任何 东西 人 栈 ， 返 回 0 。 
lua gettable 
[-1, +1, e] 


int lua gettable (lua State *L, int index); 


把 t[k] 的 值 压 栈 ， 这 里 的 t 是 指 索引 指向 的 值 ， 而 k 则 是 栈 顶 放 的 值 。 


这 个 男 数 会 弹出 堆栈 上 的 键 ， 把 结果 放 在 栈 上 相同 位 置 。 和 在 Lua 中 一 样 ， 这 个 函数 可 能 触 
发 对 应 "index" 事件 的 元 方法 (参见 8S2.4 ) 。 


返回 压 入 值 的 类 型 。 
lua gettop 
[-0， +0， 加 | 


int lua gettop (lua_ State *L); 


返回 栈 顶 元 素 的 索引 。 因为 索引 是 从 1 开始 编号 的 ， 所 以 这 个 结果 等 于 栈 上 的 元 素 个 数 ; 
特别 指出 ，0 表示 栈 为 空 。 


1Lua_getuservalue 
[-0， +1 ， 加 


int lua_ getuservalue (lua State *L, int index); 


将 给 定 索 引 处 的 用 户 数 据 所 关联 的 Lua 值 压 栈 。 
返回 压 入 值 的 类 型 。 


lJua insert 
[-1， +1， 一 


void Jua_ insert (lua_ State *L, int index); 


把 栈 顶 元 素 移动 到 指定 的 有 效 索 引 处 ， 依次 移动 这 个 索引 之 上 的 元 素 。 不 要 用 伪 索 引 来 调用 
这 个 函数 ， 因为 伪 素 引 没有 真正 指向 栈 上 的 位 置 。 


lua_Integer 


typedef ... lua_Integer; 


Lua 中 的 整数 类 型 。 


缺 省 时 ， 这 个 就 是 long long ， (通常 是 一 个 64 位 以 二 为 补 码 的 整数 ) ， 也 可 以 修改 它 为 
long 或 int (通常 是 一 个 32 位 以 二 为 补 码 的 整数 ) 。 (参见 luaconf.h 中 的 LuA_INT 
。) 


Lua 定义 了 两 个 常量 : LuA_MININTEGER 和 LUA MAXINTEGER 来 表示 这 个 类 型 可 以 表示 的 最 小 
和 最 大 值 。 


lua_isboolean 

[-0， +0， 
int Jua_isboolean (lua_ State *L, int index); 

当 给 定 素 引 的 值 是 一 个 布尔 量 时 ， 返 回 1 ， 否 则 返回 0 。 
lua_iscfunction 


[-0， +0， 


int lua_iscfunction (Jua_ State *L, int index); 


当 给 定 素 引 的 值 是 一 个 C 男 数 时 ， 返 回 1 ， 否 则 返回 0 。 


lua isfunction 
[-0， +0， 一 


int lua_isfunction (Lua_State *L, int index); 


当 给 定 素 引 的 值 是 一 个 函数 ( C 或 Lua 画 数 均 可 ) 时 ， 返 回 1 ， 


lua isinteger 
[-0， +0， 加 | 


int lua_isinteger (lua_ State *L, int index); 


当 给 定 索 引 的 值 是 一 个 整数 (其 值 是 一 个 数字 ， 且 内 部 以 整数 储存 ) ， 


回 0。 


lua islightuserdata 


[-0， +0， 


int lua_islightuserdata (lua State *L, int index); 


当 给 定 索 引 的 值 是 一 个 轻 量 用 户 数据 时 ， 返 回 1 ， 否 则 返回 0 。 


lJua isnil 


[-0， +0， 


int lua_isnil (Lua_State *L, int index); 


当 给 定 索 引 的 值 是 nil 时 ， 返 回 1 ， 否 则 返回 0 。 


lJua isnone 


[-0， +0， ] 


int lua_isnone (lJua State *L, int index); 


否则 返回 0 。 


时 ， 返 回 1， 


否则 返 


当 给 定 索 引 无 效 时 ， 返 回 1 ， 否 则 返回 0 。 
lJua isnoneornil 
[-0， +0， 二 | 


int lua_isnoneornil (lua_State *L, int index); 


当 给 定 素 引 无 效 或 其 值 是 nil 时 ， 返回 1， 否则 返回 0。 


lJua isnumber 
[-0， +0， 一 | 


int lua_isnumber (lua_State *L, int index); 


当 给 定 索 引 的 值 是 一 个 数字 ， 或 是 一 个 可 转换 为 数字 的 字符 串 时 ， 返 回 1 ， 


lua_isstring 
[-0， +0， 加 | 


int lua_isstring (Lua_State *L, int index); 


否则 返回 0 。 


当 给 定 索引 的 值 是 一 个 字符 串 或 是 一 个 数字 (数字 总 能 转换 成 字符 串 ) 时 ， 返 回 1 ， 否 则 返 


回 0 。 


lua istable 


[-0， +0， 加 


int lua_istable (lua State *L, int index); 


当 给 定 索 引 的 值 是 一 张 表 时 ， 返 回 1 ， 否 则 返回 0 。 


lua isthread 


[-0， +0， 


int lua_isthread (lua_ State *L, int index); 


当 给 定 索 引 的 值 是 一 条 线程 时 ， 返 回 1 ， 否 则 返回 0 。 


lua_ isuserdata 
[-0， +0， 加 

int lua isuserdata (lua State *L, int index); 
当 给 定 索 引 的 值 是 一 个 用 户 数据 (无 论 是 完全 的 还 是 轻 量 的 ) 时 ， 返回 1 ， 否 则 返回 0 。 
lua_ isyieldable 
[-0, +0, 一 

int lua_ isyieldable (lua State *L); 
如 果 给 定 的 协 程 可 以 让 出 ， 返 回 1 ， 否 则 返回 0。 

lua KContext 


typedef ... lua KContext; 


延续 画 数 上 下 文 参数 的 类 型 。 这 一 定 是 一 个 数字 类 型 。 当 有 intptr_t 时 ， 被 定义 为 
intptr_t ， 因此 它 也 可 以 保存 指针 。 否则 ， 它 被 定义 为 ptrdiff_t 。 


lJua KFunction 


typedef int (*lua KFunction) (lua_ State *L, int status, lua KContext ctx); 


lua len 
[-0, +1, e] 


void lua len (lua State *L, int index); 


返回 给 定 素 引 的 值 的 长 度 。 它 等 价 于 Lua 中 的 ' # ' 操作 符 (参见 83.4.7) 。 它 有 可 能 触发 
"length" 事件 对 应 的 元 方法 (参见 $2.4 ) 。 结果 压 栈 。 


lua load 


[-0， +1， 加 


int lua load (lua State *L， 
lJua_ Reader reader, 
void *data, 
const char *chunkname, 
const char *mode); 


加 载 一 段 Lua 代码 块 ， 但 不 运行 它 。 如 果 没 有 错误 ， 1ua_load 把 一 个 编译 好 的 代码 块 作为 
一 个 Lua 回 数 压 压 到 栈 顶 。 口 否则， 压 人 错 错误 消息 。 


lua_load 的 返 反 回 值 可 以 是 : 


。 LUA_oK : 没有 错误 ; 

e LUA_ERRSYNTAX : 在 预 编译 时 碰 到 语法 错误 ，; 

e ”LUA_ERRMEM : 内 存 分 配 错误 ; 

。 LUA_ERR6CMM : 在 运行 _gc 元 方法 时 出 错 了 。 【〔 这 个 错误 和 代码 块 加 载 过 程 无 关 ， 它 
是 由 垃圾 收集 器 引发 的 。) 


lua_load 回 数 使 用 一 个 用 户 提供 的 reader 男 数 来 读 取 代码 块 (人 参见 lua Reader ) 。 
data 参数 会 被 传人 reader 本 数 。 


chunkname 这 个 参数 可 以 赋予 代码 块 一 个 名 字 ， 这 个 名 字 被 用 于 出 错 信 息 和 调试 信息 (参见 
§4.9) 。 


lua_load 会 自动 检测 代码 块 是 文本 的 还 是 二 进 制 的 ， WB ie 作 (参见 程序 
luac ) 。 字符 串 mode 的 作用 和 函数 load 一 致 。 还 可 以 是 NULL 等 价 于 字符 串 


bt 。o 


lua_load 的 内 部 会 使 用 栈 ， 因此 reader 函数 必须 永远 在 每 次 返回 时 保留 栈 的 原样 。 


如 果 返 回 的 函数 有 上 值 ， 第 一 个 上 值 会 被 设置 为 保存 在 注册 表 (参见 S4.5) 
LUA_RIDX_GLOBALS 索引 处 的 全 局 环境 。 在 加 载 主 代码 块 时 ， 这 个 上 值 是 _ENv 变量 (参见 
§2.2) 。 其 它 上 值 均 被 初始 化 为 nil。 


lJua newstate 
[-0， +0， 一 


lua_State *lua newstate (lua Alloc f, void *ud); 


创建 一 个 运行 在 新 的 独立 的 状态 机 中 的 线程 。 如 果 无 法 创建 线程 或 状态 机 (由 于 内 存 有 限 ) 
则 返回 NuLL 。 参数 f 是 一 个 分 配器 画 数 ; Lua 将 通过 这 个 函数 做 状态 机 内 所 有 的 内 存 分 
配 操作 。 第 二 个 参数 ud ， 这 个 指针 将 在 每 次 调用 分 配器 时 被 转 入 。 


lua newtable 


[-0, +1, e] 


void lJua newtable (lua_ State *L); 


创建 一 张 空 表 ， 并 将 其 压 栈 。 


lua newthread 
[-0, +1, e] 


lua_State *lua newthread (lua_ State *L); 


它 等 价 于 1Lua_createtable(L，0，0) 。 


创建 一 条 新 线程 ， 并 将 其 不 压 栈 ， 并 返回 维 扩 这 个 线程 的 lua_state 指针 。 这 个 男 数 返回 的 
新 线程 共享 原 线程 的 全 局 环境 ， 但 是 它 有 独立 的 运行 栈 。 


没有 显 式 的 函数 可 以 用 来 关闭 或 销毁 掉 一 个 线程 。 


目 之 一 。 


lua newuserdata 


[-0, +1, e] 


void *]ua newuserdata (lua State *L, 


这 个 画 数 分 配 一 块 指 定 大 小 的 内 存 块 ， 

个 地 址 。 宿主 程序 可 以 随意 使 用 这 块 内 存 。 
lua next 

[-1, +(2|0), ge] 


int lua next (lua_ State *L, int index); 


从 栈 顶 弹出 一 个 键 ， 然后 把 索引 指 
对 ) 。 


典型 的 通 万 方法 是 这 样 的 : 


把 内 存 块 地 址 作为 一 个 完全 用 户 数 据 压 栈 ， 


线程 跟 其 它 Lua 对 象 一 样 是 垃圾 收集 的 条 


size_t size); 


并 返回 这 


定 的 表 中 的 一 个 键 值 对 压 栈 (弹出 的 键 之 后 的 “下 一 
如 果 表 中 以 无 更 多 元 素 ， 那么 lua_next 将 返回 0 (什么 也 不 压 栈 ) 。 


/* ” 表 放 在 索引 't' 处 */ 
lua_pushnil(L); /* 第 一 个 键 */ 
while (lua next(L, t) != 0) 
/* 使 用 ' 键 ' (在 索引 -2 处 ) 和 “' 值 ' (在 索引 -1 处) */ 
printf("%s - %s\n", 
lua typename(L, lua type(L, -2)), 
lua_ typename(L, lua type(L, -1))); 
/* 移 除 ' 值 ' ;保留 ' 键 ， 做 下 一 次 进 代 */ 
lua_pop(L, 1); 


在 通 历 一 张 表 的 时 候 ， 不 要 直接 对 键 调 用 lua_tolstring ， 除非 你 知道 这 个 键 一 定 是 一 个 字 
符 串 。 调用 lua tolstring 有 可 和 EE 改变 给 定 索 引 位置 的 值 ; 这 会 对 下 一 lJua_next 造 
成 景 搬 响 。 


关于 迭代 过 程 中 修改 被 迭代 的 表 的 注意 事项 参见 next 男 数 。 
lua Number 


typedef double lua_ Number; 


Lua 中 浮 点 数 的 类 型 。 
Lua 中 数字 的 类 型 。 缺 省 是 double ， 但 是 你 可 以 改 成 float 。 (参见 luaconf.h 中 的 
LUA_REAL 。) 


lua_ numbertointeger 


int lua_numbertointeger (lua Number n, lua_Integer *p); 


将 一 个 Lua 浮 点 数 转换 为 一 个 Lua 整数 。 这 个 宏 假设 n 有 对 应 的 整数 值 。 如 果 该 值 在 Lua 
整数 可 表示 范围 内 ， 就 将 其 转换 为 一 个 整数 赋 给 *p 。 宏 的 结果 是 一 个 布尔 量 ， 表 示 转 换 是 
否 成 功 。 注意 、 由 于 圆 整 关系 ， 这 个 范围 测试 不 用 此 宏 很 难 做 对 。) 


该 宏 有 可 能 对 其 参数 做 多 次 取 值 。 


lua_pcall 
[-(nargs + 1), +(nresults|1), 一 ] 


int lua_pcall (lua_ State *L, int nargs, int nresults, int msgh); 


以 保护 模式 调用 一 个 图 数 。 


nargs 和 nresults 的 含义 与 lua_call 中 的 相同 。 如 果 在 调用 过 程 中 没有 发 生 错 误 ， 
lua_pcall 的 行为 和 Luancall 完全 一 致 。 但 是 ， 如 果 有 错误 发 生 的 话 ， Jua_pcall 会 捕 
获 它 ， 然后 把 唯一 的 值 (错误 消息 ) 压 栈 ， 然 后 返回 错误 码 。 同 1ua_ call 一 样 ， 
Yuaneald 总 是 把 函数 本 身 和 它 的 参数 从 栈 上 移 除 。 


如 果 msgh 是 0， 返回 在 栈 顶 的 错误 消息 就 和 原始 错误 消息 完全 一 致 。 否则 ， msgh 就 被 
当成 是 错误 处 理 图 数 ER 《在 当前 的 实现 里 ， 这 个 索引 不 能 是 伪 索 引 。 ) 
在 发 生 运行 时 错误 时 ， 这 个 图 数 会 被 调用 而 参数 就 是 错误 消息 。 错误 处 理 酌 数 的 返回 值 将 被 
lua_pcall 作为 错 ed 反 回 在 堆栈 上 。 


典型 的 用 法 中 ， 条 攻关 g 数 被 用 来 给 错误 消息 加 上 更 多 的 调试 信息 ， 比如 栈 跟踪 信息 。 这 
些 信息 在 lua_pcall 返回 后 ， 由 于 栈 已 经 展开 ， 所 以 收集 不 到 了 。 


lua_pcall 豆 数 会 返回 下 列 常 数 (定义 在 lua.h 内 ) 中 的 一 个 : 
。 LUA_oK (0): 成 功 。 


e LUA_ERRRUN : 运行 时 错误 。 

。 LUA_ERRMEM : 内 存 分 配 错 误 。 对 于 这 种 错 ，Lua 不 会 调用 错误 处 理 豆 数 。 

e LUA_ERRERR : 在 运行 错误 义理 函数 时 发 生 的 错误 。 

e LUA_ERRGCMM : 在 运行 _ gc 元 方法 时 发 生 的 错误 。 (这 个 错误 和 被 调用 的 函数 无 
关 。) 


lua_ pcallk 
[-(nargs + 1), +(nresults|1), 一 ] 


int lua_pcallk (lua_ State *L, 
int nargs, 
int nresults, 
int msgh, 
Jua KContext ctx, 
lua_KFunction k); 


画 数 的 行为 和 1lua_pcall 完全 一 致 ， 只 不 还 允许 被 调用 的 函数 让 出 (参见 
es 6 


lua_pop 
[-n, +0, 一 
void lJua_ pop (lua State *L, int n); 
从 栈 中 弹出 n 个 元 素 。 
lua_pushboolean 
[-0， +1， 加 
void Jua_pushboolean (1Lua_State *L, int b); 
把 b 作为 一 个 布尔 量 压 栈 。 


lua_pushcclosure 


[-n, +1, e] 


void lua pushcclosure (lua State *L, lua_ CFunction fn, int n); 


把 一 个 新 的 C 闭 包 压 栈 。 


当 创建 了 一 个 C 画 数 后 ， 你 可 以 给 它 关 联 一 些 值 ， 这 就 是 在 创建 一 个 C 闭 包 (参见 

8$4.4) ; 接 下 来 无 论 函 数 何 时 被 调用 ， 这 些 值 都 可 以 被 这 个 画 数 访问 到 。 为 了 将 一 些 值 关联 
到 一 个 C 函数 上 ， 首先 这 些 值 需要 先 被 压 人 堆栈 〈 如 果 有 多 个 值 ， 第 一 个 先 压 ) 。 接 下 来 调 
用 lua_pushcclosure 来 创建 出 闭 包 并 把 这 个 C 本 数 压 到 栈 上 。 参数 n 告 之 范 数 有 多 少 个 
值 需 要 关联 到 范 数 上 。 1ua_pushcclosure 也 会 把 这 些 值 从 栈 上 弹出 。 


n 的 最 大 值 是 255 。 


当 n 为 需 时 ， 这 个 画 数 闻 创 建 出 一 个 轻 量 C 函数 ， 它 就 是 一 个 指向 C 函数 的 指针 。 这 种 
情况 下 ， 不 可 能 抛 出 内 存 错 误 。 


lua_ pushcfunction 
[-0， +1 ， 加 | 


void Jua_pushcfunction (lua State *L, lua CFunction f); 


范 数 压 栈 。 这 个 男 数 接收 一 个 C 函数 指针 ， 并 将 一 个 类 型 为 function 的 Lua 值 
这 个 栈 顶 的 值 被 调用 时 ， 将 触发 对 应 的 C 豆 数 。 


人 


个 C 
二 当 
注册 到 Lua 中 的 任何 范 数 都 必须 遵循 正确 的 协议 来 接收 参数 和 返回 值 (参见 lua_cFunction 
) D 


lua_pushcfunction 是 作为 一 个 宏 定 义 出 现 的 : 


#define lua pushcfunction(L,f) lua pushcclosure(L,f,0) 


lua _ pushfstring 
[-0, +1, e] 


const char *lua_pushfstring (Jua_ State *L, const char *fmt, ...); 


把 一 个 格式 化 过 的 字符 串 压 栈 ， 然后 返回 这 个 字符 串 的 指针 。 它 和 C 画 数 sprintf 比较 
像 ， 不 过 有 一 些 重要 的 区 别 : 


。 你 不 需要 为 结果 分 配 空间 : 其 结果 是 一 个 Lua 字符 串 ， 由 Lua 来 关心 其 内 存 分 配 ( 同 
时 通过 垃圾 收集 来 释放 内 存 ) 。 
。 这 个 转换 非常 的 受 限 。 不 支持 符号 、 宽 度 、 精 度 。 转换 符 只 支持 ' xx ' (插入 一 个 字符 


'%') ，"%s ' (插入 一 个 带 需 终止 符 的 字符 串 ， 没 有 长 度 限制 ), ' wf ' (插入 一 个 
lua_Number ) | (插入 一 个 lua_Integer ) "%p ” (插入 一 个 指针 或 是 一 个 十 
六 进 制 数 ) ，' wd ' (插入 一 个 int ) ，' wc' (插入 一 个 用 int 表示 的 单字 节 字 
符 ) ， 以 及 ' ww ' (插入 一 个 用 long int 表示 的 UTF-8 字 ) 。 


lua_pushglobaltable 
[-0， +1， 
void Jua_pushglobaltable (lua State *L); 
将 全 局 环境 压 栈 。 
lua_ pushinteger 
[-0， +1, 一 | 
void Jua_pushinteger (lua State *L, lua_ Integer n); 
把 值 为 n 的 整数 压 栈 。 


lua_ pushlightuserdata 
[-0， +1 ， 加 | 


void lua_ pushlightuserdata (lua State *L, void *p); 


把 一 个 轻 量 用 户 数据 压 栈 。 


用 户 数据 是 保留 在 Lua 中 的 C 值 。 轻 量 用 户 数据 表示 一 个 指针 void* 。 它 是 一 个 像 数字 一 
样 的 值 : 你 不 需要 专门 创建 它 ， 它 也 没有 独立 的 元 表 ， 而 且 也 不 会 被 收集 (因为 从 来 不 需要 
创建 ) 。 只 要 表示 的 C 地 址 相同 ， 两 个 轻 量 用 户 数 据 就 相等 。 


lua_ pushliteral 
[-0, +1, e] 


const char *lua_pushliteral (lua State *L, const char *s); 


这 个 宏 等 价 于 lua_pushlstring ， 区别 仅 在 于 只 能 在 s 是 一 个 字面 量 时 才能 用 它 。 它 会 自 


动 给 出 字符 串 的 长 度 。 


lua_pushlstring 


[-0, +1, e] 


const char *lua_pushlstring (Jua State *L, const char *s, 


把 指针 s 指向 的 长 度 为 len 的 字符 串 压 栈 。 
一 个 副本 ) ， 
串 内 可 以 是 任意 二 进 制 数据 ， 包 括 雳 字符。 


返回 内 部 副本 的 指针 。 
lua_pushnil 
[-0, +1, 一 

void lua_pushnil (lua_State *L); 
将 空 值 压 栈 。 
lua_pushnumber 


[-0， +1， 加 


因此 s 处 的 内 存在 豆 数 返回 后 ， 


size_t len); 


Lua 对 这 个 字符 串 做 一 个 内 部 副本 (或 是 复 用 
可 以 释放 掉 或 是 立刻 重用 于 其 它 用 途 。 字符 


void Jua pushnumber (lua_State *L, lua_ Number n); 


把 一 个 值 为 n 的 浮 点 数 压 栈 。 


lua_pushstring 


[-0, +1, e] 


const char *lua_pushstring (lua_State *L, const char *s); 


将 指针 s 指向 的 需 结 尾 的 字符 串 压 栈 。 
刻 重用 于 其 它 用 途 。 


返回 内 部 副本 的 指针 。 
如 果 s 为 NULL ， 将 nil 压 栈 并 返回 NULL 。 
lua_pushthread 


[-0， +1， 加 | 


因此 s 久 的 内 存在 函数 返回 后 ， 可 以 释放 掉 或 是 立 


int lua_pushthread (lua_State *L); 


把 L 表示 的 线程 压 栈 。 如 果 这 个 线程 是 当前 状态 机 的 主线 程 的 话 ， 返 回 1。 
lua_pushvalue 

[-0， +1， 一 | 
void Jua_pushvalue (lua State *L, int index); 

把 栈 上 给 定 索 引 处 的 元 素 作 一 个 副本 压 栈 。 


lua pushvfstring 


[-0, +1, e] 


const char *lua_pushvfstring (lua_ State *L， 
const char *fmt, 
va_list argp); 


等 价 于 lua pushfstring ， 不 过 是 用 va_list 接收 参数 ， 而 不 是 用 可 变数 量 的 实际 


lua_ rawequal 
[-0， +0， 加 | 


int lua rawequal (Jua_State *L, int index1, int index2); 


如 果 索 引 index1 与 索引 index2 处 的 值 本 身 相等 ( 即 不 调用 元 方法 ) ， 返 回 1 。 
回 0 。 当 任何 一 个 索引 无 效 时 ， 也 返回 0 。 


lua_rawget 
[-1, +1， 
int lua_rawget (Jua State *L, int index); 
类 似 于 1lua_gettable ， 但 是 作 一 次 直接 访问 (不 触发 元 方法 ) 。 


lua_ rawgeti 


[-0， +1， 加 


参数 。 


否则 返 


int lua_rawgeti (lua State *L, int index, lua_Integer n); 


把 t[n] 的 值 压 栈 ， 这 里 的 是 指 给 定 索 引 处 的 表 。 这 是 一 次 直接 访问 ; 就 是 说 ， 它 不 会 
触发 元 方法 。 


返回 入 栈 值 的 类 型 。 
lua_rawgetp 
[-0， +1 ， 


int lua rawgetp (lua_ State *L, int index, const void *p); 


把 t[k] 的 值 压 栈 ， 这 里 的 t 是 指 给 定 索 引 处 的 表 ， k 是 指针 p 对 应 的 轻 量 用 户 数 
据 。 这 是 一 次 直接 访问 ; 就 是 说 ， 它 不 会 触发 元 方法 。 


返回 入 栈 值 的 类 型 。 
lua_ rawlen 
[-0， +0， 一 | 


size_t Lua_rawlen (lua_State *L, int index); 


返回 给 定 索 引 处 值 的 固有 "长度 ”: 对 于 字符 串 ， 它 指 字符 串 的 长 度 ; 对 于 表 ; 它 指 不 触发 元 
方法 的 情况 下 取 长 度 操作 (' # ') 应 得 到 的 值 ; 对 于 用 户 数 据 ， 它 指 为 该 用 户 数据 分 配 的 内 
存 块 的 大 小 ; 对 于 其 它 值 ， 它 为 0。 

lua rawset 


[-2, +0, e] 


void lua rawset (lua State *L, int index); 


类 似 于 1ua_settable ， 但 是 是 做 一 次 直接 赋值 (不 触发 元 方法 ) 。 


Jua rawset1i 


[-1, +0, e] 


void lua_ rawseti (lua State *L, int index, lua_Integer i); 


等 价 于 t[i] = v ， 这 里 的 t 是 指 给 定 索 引 处 的 表 ， 而 v 是 栈 顶 的 值 。 
这 个 画 数 会 将 值 弹出 栈 。 赋值 是 直接 的 ; 即 不 会 触发 元 方法 。 
lua_rawsetp 

[-1, +0, e] 


void Jua_rawsetp (lua State *L, int index, const void *p); 


等 价 于 t[k] = v ， 这 里 的 t 是 指 给 定 索 引 处 的 表 ， k 是 指针 p 对 应 的 轻 量 用 户 数 
据 。 而 v 是 栈 顶 的 值 。 


这 个 图 数 会 业 值 弹出 栈 。 赋值 是 直接 的 ; 即 不 会 触发 元 方法 。 
lua Reader 


typedef const char * (*lua Reader) (lua State *L， 
void *data, 
SIze ut *size); 


lua_load 用 到 的 读 取 器 函数 ， 每 次 它 需 要 一 块 新 的 代码 块 的 时 候 ， 1lua_load 就 调用 读 取 
器 ， 每 次 都 会 传人 一 个 参数 data 。 读 取 器 需要 返回 含有 新 的 代码 块 的 一 块 内 存 的 指针 ， 
并 把 size 设 为 这 块 内 存 的 大 小 。 内 存 块 必须 在 下 一 次 画 数 被 调用 之 前 一 直 存 在 。 读 取 器 可 
以 通过 返回 NuLL 或 设 size 为 0 来 指示 代码 块 结束 。 读 取 器 可 能 返回 多 个 块 ， 每 个 块 可 以 
有 任意 的 大 于 需 的 尺寸 。 


lua_register 
[-0, +0, e] 


void Jua_register (lua State *L, const char *name, lua_CFunction f); 


把 C 函数 f 设 到 全 局 变量 name 中 。 它 通过 一 个 宏 定 义 : 


#define lua_register(L,n,f) 和 
(lua_pushcfunction(L, f), lua_setglobal(L, n)) 


lJua remove 
[-1, +0, 一 ] 


void lua_remove (lua State *L, int index); 


从 给 定 有 效 素 引 久 移 除 一 个 元 素 ， 把 这 个 索引 之 上 的 所 有 元 素 移 下 来 填补 上 这 个 空 除 。 不 能 
用 伪 索 引 来 调用 这 个 画 数 ， 因 为 伪 索 引 并 不 指向 真实 的 栈 上 的 位 置 。 


lua_replace 
[-1, +0， 一 | 


void lua_replace (lua State *L, int index); 


把 栈 顶 元 素 放 置 到 给 定位 置 而 不 移动 其 它 元 素 (因此 覆盖 了 那个 位 置 处 的 值 ) ， 然 后 将 栈 顶 
元 素 弹 出 。 


lua resume 
[-?， +?， 一 


int lua_resume (lua_ State *L, lua State *from, int nargs); 


在 给 定 线 程 中 启动 或 延续 一 条 协 程 。 


要 启动 一 个 协 程 的话 ， 你 需要 把 主 画 数 以 及 它 需 要 的 参数 压 入 线程 栈 ; 然后 调用 
lua_resume ， 把 nargs 设 为 参数 的 个 数 。 这 次 调用 会 在 协 程 挂 起 时 或 是 结束 运行 后 返回 。 
当 酌 数 返回 时 ， 堆 栈 中 会 有 传 给 lua_yield 的 所 有 值 ， 或 是 主 函 数 的 所 有 返回 值 。 当 协 程 
让 出 ， lua_resume 返 返回 UABMLELDS ， 若 协 程 吉 束 运行 且 没 有 任何 错误 吴 时 ， 返回 0 。 如 果 
有 错 则 返回 错误 代码 (参见 lua pcall ) 。 


在 发 生 错 误 的 情况 下 ， 堆栈 没有 展开 ， 因此 你 可 以 使 用 调试 API 来 处 理 它 。 错误 消息 放 在 
栈 顶 在 。 


要 延续 一 个 协 程 ， 你 需要 清除 上 次 lua_yield 遗留 下 的 所 有 结果 ， 你 把 需要 传 给 yield 作 
结果 的 值 压 栈 ， 然后 调用 lua_resume 。 


参数 from 表示 协 程 从 哪个 协 程 中 来 延续 L 的 。 如 果 不 存 在 这 样 一 个 协 程 ， 这 个 参数 可 以 


是 NuLL 。 


lJua rotate 
[-0， +0， 一 | 


void Jua_rotate (lua_ State *L, int idx, int n); 


把 从 idx 开始 到 栈 顶 的 元 素 轮 转 n 个 位 置 。 对 于 n 为 正 数 时 ， 轮 转 方向 是 向 栈 顶 的 ; 
当 n 为 负数 时 ， 向 栈 底 方向 轮转 -n 个 位 置 。 n 的 绝对 值 不 可 以 比 参 于 轮转 的 切片 长 度 
大 。 


lua_ setallocf 
[-0, +0, 一 

void lJua_ setallocf (lua State *L, lJua Alloc f, void *ud); 
把 指定 状态 机 的 分 配器 画 数 换 成 带 上 用 户 数 据 ud 的 Ff。 
lua_ setfield 
[-1, +0, e] 

void Jua_ setfield (lua State *L, int index, const char *k); 


做 一 个 等 价 于 trk] = v 的 操作 ， 这 里 t 是 给 出 的 索引 处 的 值 ， 而 v 是 栈 顶 的 那个 值 。 


这 个 图 数 将 把 这 个 值 弹 出 栈 。 跟 在 Lua 中 一 样 ， 这 个 函数 可 能 触发 一 个 "newindex" 事件 的 
元 方法 (参见 82.4) 。 


lua_ setglobal 
[-1, +0, e] 

void lua_setglobal (lua State *L, const char *name); 
从 堆栈 上 弹出 一 个 值 ， 并 将 其 设 为 全 局 变量 name 的 新 值 。 
lua_ seti 
[-1, +0, e] 


void lua seti (lua State *L, int index, lua_Integer n); 


做 一 个 等 价 于 trn] = v 的 操作 ， 这 里 t 是 给 出 的 索引 处 的 值 ， 而 v 是 栈 顶 的 那个 值 。 


这 个 图 数 将 把 这 个 值 弹 出 栈 。 跟 在 Lua 中 一 样 ， 这 个 画 数 可 能 触发 一 个 "newindex" 事件 的 
元 方法 (参见 82.4) 。 


lua setmetatable 


[-1， +0， 加 | 
void lJua_ setmetatable (Lua_State *L, int index); 
把 一 张 表 弹 出 栈 ， 并 将 其 设 为 给 定 索 引 处 的 值 的 元 表 。 


lua settable 
[-2, +0, e] 


void lJua_ settable (lua State *L, int index); 


做 一 个 等 价 于 t[k] = v 的 操作 ， 这 里 t 是 给 出 的 索引 处 的 值 ， v 是 栈 顶 的 那个 值 ， k 
是 栈 顶 之 下 的 值 。 


这 个 函数 会 特 键 和 值 都 弹出 栈 。 跟 在 Lua 中 一 样 ， 这 个 画 数 可 能 触发 一 个 "newindex" 事件 
的 元 方法 (参见 82.4) 。 


lua settop 


[-?, +?, —] 


void Jua_ settop (lua State *L, int index); 


参数 允许 传 入 任何 索引 以 及 0 。 它 将 把 堆栈 的 栈 顶 设 为 这 个 索引 。 如 果 新 的 栈 顶 比 原来 的 
大 ， 超出 部 分 的 新 元 素 将 被 填 为 nil 。 如 果 index 为 0， 把 栈 上 所 有 元 素 移 除 。 


lua_setuservalue 

[-1, +0, 一 | 
void Jua_setuservalue (lua State *L, int index); 

从 栈 上 弹出 一 个 值 并 将 其 设 为 给 定 索 引 处 用 户 数 据 的 关联 值 。 
lua_ State 


typedef struct lua State lua State; 


一 个 不 透明 的 结构 ， 它 指 向 一 条 线程 并 间接 (通过 该 线程 ;引用 了 整个 Lua 解释 器 的 状态 
Lua 库 是 完全 可 重 入 的 : 它 没 有 任何 全 局 变量 。 状态 机 所 有 的 信息 都 可 以 通过 这 个 结构 访问 


到 。 


这 个 结构 的 指针 必须 作为 第 一 个 参数 传递 给 每 一 个 库 辆 数 。 lua_newstate 是 一 个 例外 ， 这 
个 函数 会 从 头 创建 一 个 Lua 状态 机 。 


lua status 
[-0， +0， 一 


Int lua_status (Jua_ State *L); 


返回 线程 L 的 状态 。 


正常 的 线程 状态 是 0 ( LuA ok ) 。 当 线 程 用 lua_resume 执行 完毕 并 抛 出 了 一 个 错误 时 ， 
状态 值 是 错误 码 。 如 果 线 程 被 挂 起 ， 状 态 为 LUA_YIELD 。 


你 只 能 在 状态 为 LuA_ok 的 线程 中 调用 函数 。 你 可 以 延续 一 个 状态 为 LUA_ok 的 线程 (用 于 
开始 新 协 程 ) 或 是 状态 为 LuA_YIELD 的 线程 (用 于 延续 协 程 ) 。 


lua_stringtonumber 
[-0， +1 ， - 


size_t lua_ stringtonumber (lua_ State *L, const char *s); 
将 一 个 需 结 尾 的 字符 串 s 转换 为 一 个 数字 ， 将 这 个 数字 压 栈 ， 并 返回 字符 串 的 总 长 度 〈 即 
长 度 加 一 ) 。 转换 的 结果 可 能 是 整数 也 可 能 是 浮 点 数 ， 这 取决 于 Lua 的 转换 语法 (参见 
§3.1) 。 这 个 字符 串 可 以 有 前 置 和 后 置 的 空格 以 及 符号 。 如 果 字 符 串 并 非 一 个 有 效 的 数字 ， 


返回 0 并 不 把 任何 东西 压 栈 。 注意 ， 这 个 结果 可 以 当成 一 个 布尔 量 使 用 ， 为 真 即 转换 成 
功 。 ) 


lua toboolean 
[-0， +0， 一 | 


int lua_ toboolean (lua_ State *L, int index); 


把 给 定 索 引 处 的 Lua 值 转换 为 一 个 C 中 的 布尔 量 ( 0 或 是 1) 。 和 Lua 中 做 的 所 有 测试 一 
样 ， lua_toboolean 会 把 任何 不 同 于 false 和 nil 的 值 当 作 真 返回 ; 否则 就 返回 假 。 (如 果 
你 想 只 接收 真正 的 boolean 值 ， 就 需要 使 用 Jua_ isboolean 来 测试 值 的 类 型 。 ) 


lua tocfunction 


[-0， +0， - 


lua_CFunction lua_ tocfunction (Jua_State *L, int index); 


把 给 定 索 引 处 的 Lua 值 转换 为 一 个 C 男 数 。 这 个 值 必须 是 一 个 C 男 数 ;如果 不 是 就 返回 


NULL 。 


lua tointeger 
[-0， +0， 加 | 


lua_Integer lua tointeger (lua State *L, int index); 


等 价 于 调用 lua_tointegerx ， 其 参数 isnum 为 NULL 。 


lua tointegerx 
[-0， +0， 加 | 


lua_Integer lua tointegerx (lua_ State *L, int index, int *isnum); 


将 给 定 索 引 处 的 Lua 值 转换 为 带 符 号 的 整数 类 型 lua Integer 。 这 个 Lua 值 必须 是 一 个 整 
数 ， 或 是 一 个 可 以 被 转换 为 整数 (参见 $3.4.3) 的 数字 或 字符 串 ; 否则 ， 1lua_tointegerx 
返回 0。 


如 果 isnum 不 是 NULL ， *isnum 会 被 设 为 操作 是 否 成 功 。 


lua tolstring 
[-0, +0, e] 


const char *lua tolstring (lua_ State *L, int index, size_t *len); 


把 给 定 索 引 处 的 Lua 值 转换 为 一 个 C 字符 串 。 如 果 1len 不 为 NULL ， 它 还 把 字符 串 长 度 

设 到 *len 中 。 这 个 Lua 值 必 须 是 一 个 字符 串 或 是 一 个 数字 ; 否则 返回 返回 NuLL 。 如 果 
值 是 一 个 数字 ， 1lua_tolstring 还 会 把 堆栈 中 的 那个 值 的 实际 类 型 转换 为 一 个 字符 串 。 ( 当 
通 历 一 张 表 的 时 候 ， 若 把 lua_tolstring 作用 在 键 上 ， 这 个 转换 有 可 能 导致 lua_next 弄 

错 。 


lua_tolstring 返回 一 个 已 对 齐 指针 me Lua 状态 机 中 的 字符 串 。 这 个 字符 串 总 能 保证 〈 
C 要 求 的 ) 最 后 一 个 字符 为 需 (\0')， 它 人 允许 在 字符 串 内 包含 多 个 这 桩 的 需 。 


因为 Lua 中 可 能 发 生 垃 圾 收集 ， 所 以 不 保证 lua_tolstring 返回 的 指针 ， 在 对 应 的 值 从 堆 
栈 中 移 除 后 依然 有 效 。 


lJua tonumber 
[-0， +0， 一 


lua_ Number JIua_tonumber (Jua_State *L, int index); 


等 价 于 调用 1lua_tonumberx ， 其 参数 isnum 为 NULL 。 


lJua tonumberx 
[-0， +0， 一 


lua_Number ua_tonumberx (lua_ State *L, int index, int *isnum); 


把 给 定 索 引 处 的 Lua 值 转换 为 lua_Number 这 样 一 个 C 类 型 (参见 lua_Number ) 。 这 个 
Lua 值 必须 是 一 个 数字 或 是 一 个 可 转换 为 数字 的 字符 串 (参见 $S3.4.3) ; 否则 ， 
Jua_tonumberx 返回 0 。 


如 果 isnum 不 是 NuLL ， *isnum 会 被 设 为 操作 是 否 成 功 。 
lua topointer 
[-0, +0, 一 ] 


const void *lua topointer (lua State *L, int index); 


把 给 定 索 引 处 的 值 转换 为 一 般 的 C 指针 ( void* )。 这 个 值 可 以 是 一 个 用 户 对 象 ， 表 ， 线 程 
或 是 一 个 画 数 ; 否则 ， 1lua_topointer 返回 NULL 。 不 同 的 对 象 有 不 同 的 指针 。 不 存在 把 
指针 再 转 回 原 有 类 型 的 方法 。 


这 个 图 数 通 常 只 用 于 调试 信息 。 
lua_ tostring 
[-0, +0, e] 
const char *lua tostring (lua_ State *L, int index); 
等 价 于 调用 lua tolstring ， 其 参数 len 为 NULL 。 


lua tothread 


[-0， +0， 一 | 


lua_ State *lua tothread (JuUa_State *L, int index); 


把 给 定 索 引 处 的 值 转换 为 一 个 Lua 线程 (表示 为 lua_state* ) 。 这 个 值 必须 是 一 个 线程 ; 
否则 男 数 返回 NULL 。 


lua touserdata 
[-0， +0， 一 | 


void *lua touserdata (lua State *L, int index); 


如 果 给 定 索 引 处 的 值 是 一 个 完全 用 户 数 据 ， 画 数 返 回 其 内 存 块 的 地 址 。 如 果 值 是 一 个 轻 量 用 
户 数据 ， 那么 就 返回 它 表 示 的 指针 。 否则 ， 返 回 NULL 。 


lua_ type 
[-0， +0， 加 | 


int Jua_type (Lua_State *L, int index); 


返回 给 定 有 效 索 引 人 处 值 的 类 型 ， 当 索 引 无 效 (或 无 法 访问 ) 时 则 返回 LUA_TNONE 。 
lua_type 返回 的 类 型 被 编码 为 一 些 个 在 lua.h 中 定义 的 常量 : LUA TNIL， 
LUA_TNUMBER ， LUA_TBOOLEAN ， LUA_TSTRING ， LUA_TTABLE ， LUA_TFUNCTION ， 


LUA_TUSERDATA ， LUA_TTHREAD ， LUA_TLIGHTUSERDATA 。 
lua_typename 
[-0, +0, 一 
const char *lua_ typename (lua_ State *L, int tp); 
返回 tp 表示 的 类 型 名 ， 这 个 tp 必须 是 lua_type 可 能 返回 的 值 中 之 一 。 
lua_Unsigned 


typedef ... lua_ Unsigned; 


Jua_Integer 的 无 符号 版 本 。 


lua_ upvalueindex 


[-0， +0， 


int Jua_upvalueindex (int 工 ) ; 


返回 当前 运行 的 函数 (参见 $4.4) 的 第 i 个 上 值 的 伪 索 引 。 
lua version 
[-0, +0, V] 


const lua Number *lua_ version (lua_ State *L); 


返回 保存 在 Lua 内 核 中 储存 的 版 本 数字 的 地 址 。 当 调 用 时 传人 一 个 合法 的 lua_state ， 返 
回 创建 该 状态 机 时 的 版 本 地 址 。 如 果 用 NuLL 调用 ， 返回 调用 者 的 版 本 地 址 。 


lJua Writer 


typedef int (*lua Writer) (lua State *L, 
const void* p, 
size_t sz, 
void* ud); 


被 lJua_dump 用 到 的 写 入 器 函数 。 每 次 Jua_dump 产生 了 一 段 新 的 代码 块 ， 它 都 会 调用 写 入 
器 。 传人 要 写 入 的 缓冲 区 ( p ) 和 它 的 尺寸 ( sz ) ， 以 及 传 给 lua_dump 的 参数 data 。 


写 和 人 器 会 返回 一 个 背 误 码 : 0 表示 没有 错 错误 5 别 的 值 均 表示 一 个 营 误 ， 并 且 会 让 lua_dump 
停止 再 次 调用 写 入 器 。 


lJua xmove 


[-?, +?, —] 


void Jua xmove (lua_ State *from, lua_ State *to, int n); 


站 
A 


司 一 个 状态 机 下 不 同 线程 中 的 值 。 
这 个 豆 数 会 从 from 的 栈 上 弹出 n 个 值 ， 然后 把 它们 压 入 to 的 栈 上 。 


lua yield 


[-?, +?, 6e] 


int lua_ yield (lua_ State *L, int nresults); 


这 个 画 数 等 价 于 调用 1ua_yieldk ， 不同 的 是 不 提供 延续 函数 (参见 84.7) 。 因此 ， 当 线程 
被 延续 ， 线 程 会 继续 运行 调用 lua_yield 本 数 的 函数 。 


lua_ yieldk 
[-?, +?, 6] 


int lua _ yieldk (Jua State *L, 
int nresults, 
Jua KContext ctx, 
lua_KFunction k); 


让 出 协 程 (线程 ) 。 
当 C 画 数 调用 了 1ua yieldk ， 当前 运行 的 协 程 会 挂 起 ， 启动 这 个 线程 的 lua_resume 调用 
返回 。 参数 nresults 指 栈 上 需 返 回 给 lua_resume 的 返回 值 的 个 数 。 


当 协 程 再 次 被 延续 时 ， Lua 调用 延续 函数 k 继续 运行 被 挂 起 (参见 S4.7) 的 C 男 数 。 延续 
本 数 会 从 前 一 个 函数 中 接收 到 相同 的 栈 ， 栈 中 的 n 个 返回 值 被 移 除 而 压 人 了 从 lua_resume 
传 入 的 参数 。 此 外 ， 延 续 画 数 还 会 收 到 传 给 lua_yieldk 的 参数 ctx 。 


通常 ， 这 个 画 数 不 会 返回 ; 当 协 程 一 次 次 延续 ， 将 从 延续 画 数 继续 运行 。 然而 ， 有 一 个 例 

外 : 当 这 个 画 数 从 一 个 逐 行 运行 的 钩子 函数 (参见 S4.9) 中 调用 时 ， lua_yieldk 不 可 以 提 
供 延 续 男 数 。 (也 就 是 类 似 lua_yield 的 形式 ) ， 而 此 时 ， 钓 子 函 数 在 调用 完 让 出 后 将 立 
刻 返 回 。 Lua 会 使 协 程 让 出 ， 一 旦 协 程 再 次 被 延续 ， 触发 钓 子 的 画 数 会 继续 正常 运行 。 


当 一 个 线程 处 于 未 提供 延续 本 数 的 C 调用 中 ， 调 用 它 会 抛 出 一 个 错误 。 从 并 非 用 延续 方式 
(例如 : 主线 程 ) 启动 的 线程 中 调用 它 也 会 这 样 。 


4.9 ~- 调试 接口 


Lua 没有 内 置 的 调试 机 制 。 但 是 它 提 供 了 一 组 特殊 的 函数 接口 以 及 钩子 。 这 组 接口 可 用 于 构 
建 出 不 同 的 调试 器 、 性 能 剖析 器 、 或 是 其 它 需 要 从 解释 器 获取 “内 部 信息 "的 工具 。 


lua_Debug 


typedef struct Lua_Debug 


int event ， 
const char 
const char 
const char *what; 
const char *source; 
int currentline; 
int linedefined; 
int lastlinedefined; 
unsigned char nups; 


*name; 
* . 
namewhat ， 


unsigned char nparams ; 


char isvararg; 
char istailcall; 


és 
WW 
PA 
We 
és 
Ws 
as 
Ws 
és 
WW 
ss: 


char short_src[LUA_IDSIZE]; /* 


/* 私有 部 分 */ 


_ 其 它 域 _ 
} lua_Debug; 
这 是 一 


部 分 供 后 面 使 用 。 
下 面 对 lua_pebug 的 各 个 域 做 一 


个 函数 的 代码 块 的 名 字 。 
在 一 个 文件 中 ， 而 '@' 0 若 source 以 ' = 
由 用 户 行为 来 决定 如 何 表 示 源 码 。 


: 创建 这 


Source 


个 携带 有 有 关 画 数 或 活动 记录 的 各 种 信息 的 结构 。 
调用 Jua_getinfo 可 以 在 lua_ Debug 中 填充 那些 可 被 使 用 的 信息 域 。 


source 正 是 那个 字符 串 。 


wh 
Wh 
EA 
Wh 
wh 
WA 
wh 
上 值 的 数量 
(u) 参数 的 数量 
yf 
EA 
WY 


7 
eh 


lua_getstack 只 会 填充 结构 的 私有 


个 说 明 : 


如 果 source 以 '@' 打 头 ， 指 这 个 画 数 定义 
' 打 头 ， 剩余 的 部 分 
它 的 情况 下 ， 这 个 画 数 定义 在 一 个 字符 串 中 ， 而 


其 


short_src : 一 个 “可 打印 版 本 ”的 ”source ? 用 于 出 错 信 息 。 

linedefined : 加 数 定义 开始 处 的 行 号 。 

lastlinedefined : 图 数 定义 结束 处 的 行 号 。 

what : 如 果 男 数 是 一 个 Lua 画 数 ， 则 为 一 个 字符 串 "Lua" ; 如 果 是 一 个 C 玉 数 ， 则 为 
"c" ;如 果 它 是 一 个 代码 块 的 主体 部 分 ， 则 为 "main" 。 

currentline : 给 定 本 数 正在 执行 的 那 一 行 。 当 提供 不 了 行 号 信息 的 时 候 ， currentline 
被 设 为 -1 。 

name : 给 定 画 数 的 一 个 合理 的 名 字 。 因为 Lua 中 的 函数 是 一 等 公民 ， 所 以 它们 没有 回 
定 的 名 字 : 一 些 范 数 可 能 是 全 局 复合 变量 的 值 ， 另 一 些 可 能 仅仅 只 是 被 保存 在 一 张 表 的 
某 个 域 中 。 1ua_getinfo 辑 数 会 检查 函数 是 怎样 被 调用 的 ， 以 此 来 找到 一 个 适合 的 名 
字 。 如 果 它 找 不 到 名 字 ， name 就 被 设置 为 NuLL 。 

namewhat : 用 于 解释 name 域 。 namewhat 的 值 可 以 是 "global" ，"local"， 
"method" ， "field" ， "upvalue" , 或 是 " ( 空 串 ) 。 这 取决 于 画 条 数 怎 样 被 调用 。 
(Lua 用 空 串 表示 其 它 选项 都 不 符合 。 

istailcall : 如 果 画 数 以 尾 调用 形式 调用 ， 这 个 值 就 为 真 。 在 这 种 情况 下 ， 当 层 的 调用 
者 不 在 栈 中 。 

nups : 函数 的 上 值 个 数 。 

nparams : 图 数 固定 形 参 个 数 (对 于 C 男 数 永远 是 0 ) 。 

isvararg : : 如 果 函 数 是 一 个 可 变 参 数 画 数 则 为 真 (对 于 C 辑 数 永远 为 真 ) 。 


lua_gethook 


[-0, +0, 一 


lua_Hook lua_gethook (Jua State *L); 


返回 当前 的 钧 子 本 数 。 
lua_ gethookcount 
[-0， +0， 加 | 


int lua gethookcount (Jua_ State *L); 


返回 当前 的 钩子 计数 。 


lua_ gethookmask 
[-0， +0， 加 | 


int lua gethookmask (Jua_State *L); 


返回 当前 的 钓 子 掩 码 。 
lua getinfo 


[-(011), +(011|2), e] 


int lua getinfo (lua State *L, const char *what, lua_Debug *ar); 


返回 一 个 指定 的 范 数 或 一 数 调用 的 信息 。 


当 用 于 取得 一 次 函数 调用 的 信息 时 ， 参数 ar 必须 是 一 个 有 效 的 活动 的 记录 。 这 条 记录 可 以 
是 前 一 次 调用 1ua_getstack 得 到 的 ， 或 是 一 个 钩子 (参见 lua_Hook ) 得 到 的 参数 。 


甘 取 一 个 画 数 的 信息 时 ， 可 以 把 这 个 画 数 矿 入 堆栈 ， 然后 把 what 字符 串 以 字符 

' 起 头 。 (这 会 让 lua_getinfo 从 栈 顶 上 弹出 画 数 。) 例如 ， 想 知道 函数 f 是 在 哪 
一 行 定义 的 ， 你 可 以 使 用 下 列 代 码 : 

Jua_ Debug ar 

lua_getglobal(L，"f"); /* 取得 全 局 变量 'f' */ 


Jua_getinfo(L, ">S", &ar); 
printf("%d\n", ar.linedefined); 


what 字符 串 中 的 每 个 字符 都 筛选 出 结构 ar 结构 中 一 些 域 用 于 填充 ， 或 是 把 一 个 值 压 人 堆 
栈 : 


e"'n "填充 name 及 namewhat 域 ; 

© 'S": 填充 source ， short_src ， linedefined ， Jastlinedefined ， 以 及 what 
域 ; 

e "1 填充 currentline 域 ; 

e 't' 填充 istailcall 域 ; 

e。 'u' 填 充 nups ， nparans ， 及 pr 域 ; 


。 'f ": 把 正在 运行 中 指定 层次 处 图 数 压 
。"L “将 一 张 表 压 栈 ， ne J 是 有 效 行 。 (有 效 行 指 
有 实际 代码 的 行 ， 即 你 可 以 置 入 断 点 的 行 。 无 效 行 包括 空 行 和 只 有 注释 的 行 。) 


如 果 这 个 选项 和 选项 ' f ' 同时 使 用 ， 这 张 表 在 函数 之 后 压 栈 。 
站 公有 反 


画 数 出 错 会 返回 0 (例如 ， what 中 有 一 个 无 效 选项 ) 。 


lua getlocal 
[-0, +(0|1), 二 ] 


const char *lua getlocal (lua State *L, const lua Debug *ar, int n); 


从 给 定 活动 记录 或 从 一 个 函数 中 获取 一 个 局 部 变量 的 信息 。 


对 于 第 一 种 情况 ， 参数 ar 必须 是 一 个 有 效 的 活动 的 记录 。 这 条 记录 可 以 是 前 一 次 调用 
lua_getstack 得 到 的 ， 或 是 一 个 钩子 (参见 1ua_Hook ) 的 参数 。 索引 n 用 于 选择 要 检 
阅 哪个 局 部 变量 ; 参见 debug.getlocal 中 关于 变量 的 索引 和 名 字 的 介 绍 。 


lua_getlocal 将 变量 的 值 压 栈 ， 并 返回 其 名 字 。 


对 于 第 二 种 情况 ， ar 必须 填 NuLL 。 需要 探知 的 函数 必须 放 在 栈 顶 。 对 于 这 种 情况 ， 只 有 
Lua 画 数 的 形 参 是 可 见 的 (没有 关于 还 有 哪些 活动 变量 的 信息 ) 也 不 会 有 任何 值 压 栈 。 


还 
当 索 引 大 于 活动 的 局 部 变量 的 数量 ， 返回 NuLL (无 任何 压 栈 ) 
lua getstack 
[-0， +0， 加 | 


int lua getstack (lua_ State *L, int lJevel, lua _ Debug *ar); 


获取 解释 器 的 运行 时 栈 的 信息 。 


这 个 函数 用 正在 运行 中 的 指定 层次 处 函数 的 活动 记录 来 填写 1ua Debug 结构 的 一 部 分 。 0 
层 表 示 当 前 运行 的 画 数 ， n+1 层 的 琅 数 就 是 调用 第 n 层 〈 尾 调用 例外 ， 它 不 算 在 栈 层 次 中 ) 
函数 的 那 一 个 。 如 果 没 有 错误 ， 1lua_getstack 返回 1 ; 当 调 用 传人 的 层次 大 于 堆栈 深度 的 


时 候 ， 返 回 0 。 


lua_getupvalue 
[-0, +(0|1), 


const char *lua getupvalue (lua State *L, int funcindex, int n); 


获取 一 个 闭 包 的 上 值 信息 。 (对 于 Lua 豆 数 ， 上 值 是 函数 需要 使 用 的 外 部 局 部 变量 ， 因此 这 
些 变量 被 包含 在 闭 包 中 。) 1ua_ getupvalue 获取 第 n 个 上 值 ， 把 这 个 上 值 的 值 压 栈 ， 并 
且 返 回 它 的 名 字 。 funcindex 指向 闭 包 在 栈 上 的 位 置 。 ( 因为 上 值 在 整个 函数 中 都 有 效 ， 
所 以 它们 没有 特别 的 次 序 。 因此 ， 它 们 以 字母 次 序 来 编号 。) 


当 索 引号 比 上 和 值 数量 大 的 时 候 ， 返回 NuLL (而 且 不 会 压 人 任何 东西 ) 。 对 于 C 男 数 ， 所 有 
上 值 的 名 字 都 是 空 串 "" 。 


lua Hook 


typedef void (*lua Hook) (lua State *L, lua Debug *ar); 


用 于 调试 的 钩子 函数 类 型 。 


无 论 何 时 钧 子 被 调用 ， 它 的 参数 ar 中 的 event 域 都 被 设 为 触发 钧 子 的 事件 。 Lua 把 这 些 
事件 定义 为 以 下 常量 : LUA HOOKCALL ， LUA_HOOKRET ， 
LUA_HOOKTAILCALL ， LUA_HOOKLINE ， ”LUA_HoOKCOUNT 。 除 此 之 外 ， 对 于 line 事件 ， 


currentline 域 也 被 设置 。 要 想 获 得 ar 中 的 其 他 域 ， 钩子 必 须 调用 lua getinfo 。 


对 于 call 事件 ， event 可 以 是 LUA HookcALL 这 个 通常 值 ， 或 是 LuA_HookTAILCALL 表示 尾 
调用 ; 后 一 种 情况 ， 没 有 对 应 的 返回 事件 。 


当 Lua 运行 在 一 个 钩子 内 部 时 ， 它 将 屏蔽 掉 其 它 对 钩子 的 调用 。 也 就 是 说 ， 如 果 一 个 钩子 函 
数 内 再 调 回 Lua 来 执行 一 个 画 数 或 是 一 个 代码 块 ， 这 个 执行 操作 不 会 触发 任何 的 钩子 。 


钓 子 函数 不 能 有 延续 点 ， 即 不 能 用 一 个 非 空 的 k 调用 lua _ yieldk ， lua pcallk ， 或 
Jua callk 。 


钧 子 范 数 可 以 在 满足 下 列 条 件 时 让 出 : 只 有 行 计数 事件 可 以 让 出 ， 且 不 能 在 让 出 时 传 出 任何 
值 ; 从 钩子 里 让 出 必须 用 1ua yield 来 结束 钩子 的 运行 ， 且 nresults 必须 为 需 。 


lua sethook 
[-0， +0， 一 | 


void lua_sethook (lua_ State *L, lua_ Hook f, int mask, int count); 


设置 一 个 调试 用 钩子 范 数 。 
参数 f 是 钩子 函数 。 mask 指定 在 哪些 事件 时 会 调用 : 它 由 下 列 一 组 位 常量 构成 


LUA_MASKCALL ， LUA_MASKRET ， LUA_MASKLINE ， LUA_MASKCOUNT 。 参数 count 只 在 掩 码 


中 包含 有 LuA_MAskcouNT 才 有 意义 。 对 于 每 个 事件 ， 钧 子 被 调用 的 情况 解释 如 下 : 


。 call hook: 在 解释 器 调用 一 个 图 数 时 被 调用 。 钩子 将 于 Lua 进入 一 个 新 男 数 后 ， 男 数 获 
取 参 数 前 被 调用 。 


。 return hook: 在 解释 器 从 一 个 画 数 中 返回 时 调用 。 钧 子 将 于 Lua 离开 函数 之 前 的 那 一 刻 
被 调用 。 没有 标准 方法 来 访问 被 画 数 返回 的 那些 值 。 

。 line hook: 在 解释 器 准备 开始 执行 新 的 一 行 代码 时 ， 或 是 跳 转 到 这 行 代 码 中 时 (即使 在 
同一 行内 跳 转 ) 被 调用 。 这 个 事件 仅仅 在 Lua 执行 一 个 Lua 琅 数 时 发 生 。) 

。 count hook: 在 解释 器 每 执行 count 条 指使 后 被 调用 。 【〔 这 个 事件 仅仅 在 Lua 执行 一 
个 Lua 责 数 时 发 生 。) 


钩子 可 以 通过 设置 mask 为 规 屏 向。 
lua setlocal 
[-(0|1), +0, 一 


const char *lua_ setlocal (lua State *L, const lua _ Debug *ar, int n); 


置 给 定 活动 记录 中 的 局 部 变量 的 值 。 参数 ar 与 n 和 1ua uetlocal 中 的 一 样 (参见 
Jua getlocal ) lJua_setlocal 把 栈 顶 的 值 赋 给 变量 然后 返回 变量 的 名 字 。 它 会 将 值 从 覆 
顶 弹 出 。 


当 索 引 大 于 活动 局 部 变量 的 数量 时 ， 返 回 NuLL (什么 也 不 弹出 ) 。 
lua_setupvalue 
[-(011), +0, 二 ] 


const char *lua_ setupvalue (lua_ State *L, int funcindex, int n); 


设置 闭 包 上 值 的 值 。 它 把 栈 顶 的 值 弹 出 并 赋 于 上 值 并 返回 上 值 的 名 字 。 参数 funcindex 与 
n 和 lua_getupvalue 中 的 一 样 (参见 lua_getupvalue ) 。 


当 索 引 大 于 上 值 的 数量 时 ， 返 回 NuLL (什么 也 不 弹出 ) 。 


lua_ upvalueid 


[-0， +0， 加 | 


void *]ua upvalueid (lua_ State *L, int funcindex, int n); 


返回 索引 funcindex 处 的 闭 包 中 编号 为 n 的 上 值 的 一 个 唯一 标识 符 。 参数 funcindex 与 
和 1ua_getupvalue 中 的 一 样 (参见 1ua getupvalue ) 。 (但 n 不 可 以 大 于 上 值 的 数 


lm = 
— 
O 


这 些 唯一 标识 符 可 用 于 检测 不 同 的 闭 包 是 否 共享 了 相同 的 上 值 。 共享 同一 个 上 值 的 Lua 闭 包 
《 即 它们 指 的 同一 个 外 部 局 部 变量 ) 会 针对 这 个 上 值 返回 相同 的 标识 。 


lua_upvaluejoin 
[-0， +0， 加 | 


void Jua upvaluejoin (1Lua_State *L, int funcindex1, int nl1， 
int funcindex2, int n2); 


让 索引 funcindex1 处 的 Lua 闭 包 的 第 ni 个 上 值 引用 索引 funcindex2 处 的 Lua 闭 包 的 
第 n2 个 上 值 。 


5 一 辅助 库 


辅助 库 提供 了 一 些 便捷 函数 ， 方 便 在 C 中 为 Lua 编程 。 基础 AP| 提供 了 C 和 Lua 交互 用 的 
主要 责 数 ， 而 辅助 库 则 为 一 些 常见 的 任务 提供 了 高 阶 画 数 。 


所 有 辅助 库 中 的 函数 和 类 型 都 定义 在 头 文件 lauxlib.h 中 ， 它们 均 带 有 前 级 lual 。 


辅助 库 中 的 所 有 画 数 都 基于 基础 API 实现 。 故而 它们 并 没有 提供 任何 基础 API 实现 不 了 的 功 
能 。 虽然 如 此 ， 使 用 辅助 库 可 以 让 你 的 代码 更 为 健壮 。 


一 些 辅助 库 图 数 会 在 内 部 使 用 一 些 额 外 的 栈 空间 。 当 辅 助 库 使 用 的 栈 空间 少 于 五 个 时 ， 它们 
不 去 检查 栈 大 小 ; 而 是 简单 的 假设 栈 够 用 。 


一 些 辅助 库 中 的 函数 用 于 检查 C 男 数 的 参数 。 因为 错误 信息 格式 化 为 指 代 参数 〈 例 
如 ，" "bad argument #1 ") y 你 就 不 要 把 这 些 函 半数 用 于 参数 之 外 的 值 了 。 


如 果 检 查 无 法 通过 ， 1uaL_check* 这 些 函 数 一 定 会 抛 出 错误 。 


5.1 一 洲 数 和 类 型 
这 里 我 们 按 字母 表 次 序列 出 了 辅助 库 中 的 所 有 辑 数 和 类 型 。 


lualL addchar 


[-?, +?, 6] 
void JuaL_addchar (lual_ Buffer *B, char c); 
向 缓存 B (参见 lual Buffer ) 添加 一 个 字 节 c。 


lualL addlstring 


[-?, +?, 6e] 


void JuaL_addlstring (LuaL_Buffer *B, const char *s, size_t 1); 


向 缓存 B (参见 lual_Buffer ) 添加 一 个 长 度 为 1 的 字符 串 s 。 这 个 字符 串 可 以 包含 


LuaL_addsize 


[-?, +?, 6e] 


void JuUaL_addsize (lual Buffer *B, size t n); 


向 缓存 B (参见 Jual_Buffer ) 添加 一 个 已 在 之 前 复制 至 1 缓冲 区 (参见 
luaL_prepbuffer ) 的 长 度 为 n 的 字符 串 。 


lualL addstring 
[-?, +?, 6] 


void JuaL_addstring (luaLl Buffer *B, const char *s); 


向 缓存 B (参见 lual Buffer ) 添加 一 个 雾 结尾 的 字符 串 s 。 
lualL addvalue 
[-1, +?, e] 

void JuaL_addvalue (lual_ Buffer *B); 


向 缓存 B (参见 lual Buffer ) 添加 栈 顶 的 一 个 值 ， 随 后 将 其 弹出 。 


这 个 事 数 是 操作 字符 串 缓 存 的 画 数 中 ， 唯 一 一 个 会 ( 且 必 须 ) 在 栈 上 放置 额外 元 素 的 。 这 个 
元 素 将 被 加 入 缓存 。 


lualL_ argcheck 


[-0, +0, v] 
void JUaL_argcheck (lua State *L, 
int cond, 
int arg, 


const char *extramsg); 


检查 cond 是 否 为 真 。 如 果 不 为 真 ， 以 标准 信息 形式 抛 出 一 个 错误 (参见 


Jual_argerror ) o 


lualL argerror 
[-0, +0, V] 


int lual_argerror (lua State *L, int arg, const char *extramsg); 


抛 出 一 个 错误 报告 调用 的 C 画 数 的 第 arg 个 参数 的 问题 。 它 使 用 下 列 标准 信息 并 包含 了 一 
段 extramsg 作为 注解 : 


bad argument # arg_ to '_funcname_' (_extramsg_) 


这 个 贺 数 永远 不 会 返回 。 


lual Buffer 


typedef struct lual_Buffer luaLl_Buffer; 


字符 串 缓存 的 类 型 。 
字符 串 缓存 可 以 让 C 代码 分 段 构造 一 个 Lua 字符 串 。 使 用 模式 如 下 : 


。 首先 定义 一 个 类 型 为 lual Buffer 的 变量 bp 。 

e。 调用 luaL_buffinit(L，&b) 初始 化 它 。 

。 然后 调用 lual_add* 这 组 函数 向 其 添加 字符 串 片断 。 

。 最 后 调用 luaL_pushresult(&b) 。 最 后 这 次 调用 会 在 栈 顶 留 下 最 终 的 字符 串 。 


如 果 你 预先 知道 结果 串 的 长 度 ， 你 可 以 这 样 使 用 缓存 : 


。 首先 定义 一 个 类 型 为 lual_Buffer 的 变量 b 。 

e。 然后 调用 1luaL_buffinitsize(L，&b，sz) 预 分 配 sz 大 小 的 空间 。 

。 接着 将 字符 串 复 制 人 这 个 空间 。 

。 最 后 调用 luaL_pushresultsize(&b，sz) ， 这 里 的 sz 指 已 经 复制 到 缓存 内 的 字符 串 长 
度 。 


一 般 的 操作 过 程 中 ， 字 符 串 缓存 会 使 用 不 定量 的 栈 槽 。 因此 ， 在 使 用 缓存 中 ， 你 不 能 假定 目 
前 栈 顶 在 哪 。 在 对 缓存 操作 的 函数 调用 间 ， 你 都 可 以 使 用 栈 ， 只 需要 保证 栈 平衡 即 可 ; 即 ， 
在 你 做 一 次 缓存 操作 调用 时 ， 当 时 的 栈 位 置 和 上 次 调用 缓存 操作 后 的 位 置 相同 。 《对 于 
luaL_addvalue 是 个 唯一 的 例外 。) 在 调用 完 luaL_pushresult 后 ， 栈 会 恢复 到 缓存 初始 化 
时 的 位 置 上 ， 并 在 顶部 压 人 最 终 的 字符 串 。 


LuaL_buffinit 
[-0， +0， -] 


void lual buffinit (lua_ State *L, lual Buffer *B); 


初始 化 缓存 6 。 这 个 画 数 不 会 分 配 任何 空间 ; 缓存 必须 以 一 个 变量 的 形式 声明 (参见 


Jual_Buffer ) o 


lualL buffinitsize 
[-?, +?, 6] 


char *]luaL_buffinitsize (lua State *L, lual_ Buffer *B, size _t sz); 


等 价 于 调用 序列 Luamoufbinsen, Jual_prepbuffsize 。 
lualL callmeta 
[-0, +(011), el 

int lual_callmeta (lua_ State *L, int obj, const char *e); 


调用 一 个 元 方法 。 


如 果 在 索引 obj 处 的 对 象 有 元 表 ， 且 元 表 有 域 。。 这 个 画 数 会 以 该 对 象 为 参数 调用 这 个 
域 。 这 种 情况 下 ， 画 数 返回 真 并 将 调用 返回 值 压 栈 。 如 果 那 个 位 置 没有 元 表 ， 或 没有 对 应 的 
元 方法 ， 此 画 数 返 回 假 (并 不 会 将 任何 东西 压 栈 ) 。 


lual_checkany 
[-0, +0, v] 
void JuaL_checkany (lua State *L, int arg); 
令 查 豆 数 在 arg 位 置 是 否 有 任何 类 型 (包括 nil) 的 参数 。 


lualL_ checkinteger 
[-0, +0, V] 


lua_Integer lual_checkinteger (Jua State *L, int arg); 


检查 函数 的 第 arg 个 参数 是 否 是 一 个 整数 (或 是 可 以 被 转换 为 一 个 整数 ) 并 以 
Jua_Integer 类 型 返回 这 个 整数 值 。 


lualL_checklstring 
[-0, +0, v] 


const char *lual_checklstring (lua_ State *L, int arg, size t *]); 


检查 函数 的 第 arg 个 参数 是 否 是 一 个 字符 串 ， 并 返回 该 字符 串 ; 如 果 1 不 为 NuLL ， 将 
字符 串 的 长 度 填 人 *1 。 


画 数 使 用 lua_tolstring 来 获取 结果 。 所 以 该 函数 有 可 能 引发 的 转换 都 同样 有 效 。 
lual checknumber 
[-0, +0, v] 


lua_Number LuaL_checknumber (lua_ State *L, int arg); 


仿 查 图 数 的 第 arg 个 参数 是 否 是 一 个 数字 ， 并 返回 这 个 数字 。 
luaL_checkoption 
[-0, +0, v] 


int lual_checkoption (lJua State *L， 
int arg, 
const char *def, 
const char *const lst[]); 


检查 图 数 的 第 arg 个 参数 是 否 是 一 个 字符 串 ， 并 在 数组 lst 【〈 上 比如 是 需 结 尾 的 字符 串 数 
组 ) 中 查找 这 个 字符 串 。 返回 匹配 到 的 字符 串 在 数组 中 的 索引 号 。 如 果 参 数 不 是 字符 串 ， 或 
是 字符 串 在 数组 中 匹配 不 到 ， 都 将 抛 出 错误 。 


如 果 def 不 为 NULL ， 辑 数 就 把 def 当 作 默认 值 。 默认 值 在 参数 arg 不 存在 ， 或 该 参数 
是 nil 时 生效 。 


这 个 酌 数 通常 用 于 将 字符 串 映射 为 C 枚 举 量 。 (在 Lua 库 中 做 这 个 转换 可 以 让 其 使 用 字符 
串 ， 而 不 是 数字 来 做 一 些 选项 。 ) 


lual checkstack 
[-0, +0, V] 


void JuaL_checkstack (lua_ State *L, int sz, const char *msg); 


将 栈 空间 扩展 到 top + sz 个 元 素 。 如 果 扩 展 不 了 ， 则 抛 出 一 个 错误 。 msg 是 用 于 错误 消 
息 的 额外 文本 ( NULL 表示 不 需要 额外 文本 ) 。 


luaL_checkstring 


[-0, +0, V] 


const char *lual_checkstring (lua_ State *L, int arg); 


检查 函数 的 第 arg 个 参数 是 否 是 一 个 字符 串 并 返回 这 个 字符 串 。 
这 个 函数 使 用 lua_tolstring 来 获取 结果 。 所 以 该 范 数 有 可 能 引发 的 转换 都 同样 有 效 。 


lualL_checktype 

[-0, +0, V] 
void JuaL_checktype (lua_ State *L, int arg, int t); 

令 查 图 数 的 第 arg 个 参数 的 类 型 是 否 是 t 。 参见 lua_type 查阅 类 型 t 的 编码 。 
lualL checkudata 

[-0, +0, V] 


void *]ual_checkudata (lua State *L, int arg, const char *tname); 


查 函 数 的 第 arg 个 参数 是 否 是 一 | 类 型 为 tname 的 用 户 数 据 (参见 lual newmetatable 
)。 它 会 返回 该 用 户 数据 的 地 址 (参见 lua_touserdata ) 。 


lJual checkversion 
[-0， +0， 一 


void JUaL_checkversion (lua State *L); 


检查 调用 它 的 内 核 是 否 是 创建 这 个 Lua 状态 机 的 内 核 。 以 及 调用 它 的 代码 是 否 使 用 了 相同 的 
Lua 版 本 。 同时 也 检查 调用 它 的 内 核 与 创建 该 Lua 状态 机 的 内 核 是 否 使 用 了 同一 片 地 址 空 
间 。 


lual_dofile 
[-0, +?, e] 

int lual_dofile (lua State *L, const char *filename); 
加 载 并 运行 指定 的 文件 。 它 是 用 下 列 宏 定义 出 来 : 


(lual_loadfile(L, filename) || lua_pcall(L, 0, LUA MULTRET, 0)) 


如 果 没 有 错误 ， 本 数 返 回 假 ; 9 有 错 则 返 回 真 。 
lual_dostring 
[-0， +?, 加 | 
int lual_dostring (Lua_State *L, const char *str); 
加 载 并 运行 指定 的 字符 串 。 它 是 用 下 列 宏 定义 出 来 : 
(lual_loadstring(L, str) || lua pcall(L, 0, LUA_ MULTRET, 0)) 
如 果 没 有 错误 ， 画 数 返 回 假 ; y 有 错 则 返 回 真 。 


lJual error 
[-0, +0, V] 


int lual_error (lua_ State *L, const char *fmt, ...); 


抛 出 一 个 错误 。 错误 消息 的 格式 由 fmt 给 出 。 后 面 需 提供 若干 参数 ， 这 些 参 数 遵 循 
lua_pushfstring 中 的 规则 。 如 果 能 获得 相关 信息 ， 它 还 会 在 消息 前 面 加 上 错误 发 生 时 的 文 
件 名 及 行 号 。 


函数 永远 不 会 返回 。 但 是 在 C 画 数 中 通常 遵循 惯用 法 : return luaL_error(_args_) 。 
lual execresult 
[-0, +3, e] 
int LuaL_execresult (lua State *L, int stat); 


这 个 画 数 用 于 生成 标准 库 中 和 进程 相关 事 数 的 返回 值 。 ( 指 os.execute 和 io.close ) 。 


lual fileresult 
[-0, +(1|3), e] 


int lual_fileresult (lua State *L, int stat, const char *fname); 


这 个 画 数 用 于 生成 标准 库 中 和 文件 相关 的 函数 的 返回 值 。 ( 指 ( io.open ， os.rename， 


file:seek ， 等 5 )。 


1LuaL_getmetafield 
[-0, +(0|1), el 


int lual getmetafield (lua State *L, int obj, const char *e); 


将 索引 obj 处 对 象 的 元 表 中 e 域 的 值 压 栈 。 如 果 该 对 象 没有 元 表 ， 或 是 该 元 表 没 有 相关 
域 ， 此 函数 什么 也 不 会 压 栈 并 返回 LUA_TNIL 。 


lualL getmetatable 
[-0， +1 ， 加 | 


int lual_getmetatable (lua_ State *L, const char *tname ) ， 


将 注册 表 中 tname 对 应 的 元 表 (参见 lual newmetatable ) 压 栈 。 如 果 没 有 tname 对 应 的 
元 表 ， 则 将 nil 压 栈 并 返回 假 。 


lualL getsubtable 
[-0, +1, e] 


int lual_getsubtable (lua State *L, int idx, const char *fname); 


确保 tr[fname] 是 一 张 表 ， 并 将 这 张 表 压 栈 。 这 里 的 t 指 索引 idx 人 处 的 值 。 如 果 它 原来 
就 是 一 张 表 ， 返 回 真 ; 否则 为 它 创 建 一 张 新 表 ， 返 回 假 。 


lualL_gsub 
[-0, +1, e] 


const char *lual_gsub (lua_ State *L, 
const char *s, 
const char *p, 
const char *r); 


将 字符 串 s 生成 一 个 副本 ， 并 将 其 中 的 所 有 字符 串 p 都 替换 为 字符 串 r 。 将 结果 串 压 
栈 并 返回 它 。 


lual len 


[-0, +0, e] 


lua_Integer lual len (lua State *L, int index); 


以 数字 形式 返回 给 定 索 引 处 值 的 “长度 ”; 它 等 价 于 在 Lua 中 调用 ' # ' 的 操作 (参见 
§3.4.7) 。 如 果 操 作 结果 不 是 一 个 整数 ， 则 抛 出 一 个 错误 。 【〔 这 种 情况 只 发 生 在 触发 元 方法 
时 。) 


lual loadbuffer 
[-0， +1， 一 | 


Int lual_ loadbuffer (lua State *L, 
const char *buff, 
STzeOB Sz) 
const char *name); 


等 价 于 lual loadbufferx ， 其 mode 参数 等 于 NULL 。 


lual loadbufferx 
[-0， +1， 一 | 


int lual_loadbufferx (lua State *L， 
const char *buff, 
STZet SZ 
const char *name, 
const char *mode); 


把 一 段 缓存 加 载 为 一 个 Lua 代码 块 。 这 个 函数 使 用 lua_load 来 加 载 buff 指向 的 长 度 为 
sz 的 内 存 区 。 


这 个 函数 和 lua_load 返回 值 相 同 。 name 作为 代码 块 的 名 字 ， 用 于 调试 信息 和 错误 消息 。 
mode 字符 串 的 作用 同 函 数 lua_ load 。 


lual_loadfile 
[-0, +1, e] 

int lual loadfile (lua State *L, const char *filename); 
等 价 于 lualL_ loadfilex ， 其 mode 参数 等 于 NULL 。 


lual loadfilex 


[-0, +1, e] 


int lual_loadfilex (Jua_State *L, const char *filename, 
const char *mode); 


把 一 个 文件 加 载 为 Lua 代码 块 。 这 个 回 数 使 用 1ua 1oad 加 载 文件 中 的 数据 。 代码 块 的 名 字 
被 命名 为 filename o 如 果 filename 为 NULL ， 它 从 标准 输入 加 载 。 如 果 文 件 的 第 一 行 以 
# 打头 ， 则 忽略 这 一 行 。 


mode 字符 串 的 作用 同 函 数 lua_ load 。 


此 函数 的 返回 值 科 lua_load 相同 ， 不 过 它 还 可 能 产生 一 个 叫做 LuA_ERRFILE 的 出 错 码 。 这 
种 错误 发 生 于 无 法 打开 或 读 入 文件 时 ， 或 是 文件 的 模式 错误 。 


和 lua_load 一 样 ， 这 个 本 数 仅 加 载 代 码 块 不 运行 。 
lual loadstring 
[-0， +1， 
int lual loadstring (lua State *L, const char *s); 
将 一 个 字符 串 加 载 为 Lua 代码 块 。 这 个 画 数 使 用 lua_load 加 载 一 个 需 结 尾 的 字符 串 s 。 


此 函数 的 返回 值 和 Jua_ load 相 同 。 


也 和 1lua load 一 样 ， 这 个 图 数 仅 加 载 代 码 块 不 运行 。 
lual newlib 
[-0, +1, e] 
void Jual_ newlib (lua_ State *L, const lual_ Reg 1[]); 
创建 一 张 新 的 表 ， 并 把 列表 1 中 的 函数 注册 进去 。 
它 是 用 下 列 宏 实现 的 : 

(lualL_newlibtable(L,1), lual_setfuncs(L,1.,0)) 
数组 1 必须 是 一 个 数组 ， 而 不 能 是 一 个 指针 。 
lualL newlibtable 


[-0, +1, e] 


void Jual_newlibtable (Lua_State *L, const lual_ Reg 1[]); 


创建 一 张 新 的 表 ， 并 预 分 配 足 够 保存 下 数组 1 内 容 的 空间 (但 不 填充 ) 。 这 是 给 
Jual_setfuncs 一 起 用 的 (参见 lual_newlib ) o 


它 以 宏 形式 实现 ， 数组 1 必须 是 一 个 数组 ， 而 不 能 是 一 个 指针 。 
lJual newmetatable 
[-0, +1, e] 


int lual_newmetatable (lua_ State *L, const char *tname); 


如 果 注 册 表 中 已 存在 键 tname ， 返 回 0 。 否则 ， 为 用 户 数据 的 元 表 创 建 一 张 新 表 。 向 这 张 
表 加 入 _name = tname 键 值 对 ， 并 将 [tname] = new table 添加 到 注册 表 中 ， 返回 1 。 
( _name 项 可 用 于 一 些 错误 输出 函数 。) 


这 两 种 情况 都 会 把 最 终 的 注册 表 中 关联 tname 的 值 压 栈 。 
lualL newstate 
[-0， +0， 


lua_State *lual_ newstate (void); 


创建 一 个 新 的 Lua 状态 机 。 它 以 一 个 基于 标准 C 的 realloc 画 数 实现 的 内 存 分 配器 调用 
lua_newstate 。 并 把 可 打印 一 些 出 错 信息 到 标准 错误 输出 的 panic 内 轴 数 (参见 84. 6) 设置 
好 ， 用 于 义理 致命 错误 。 


返回 新 的 状态 机 。 如 果 内 存 分 配 失败 ， 则 返回 NULL 。 
lualL_openlibs 
[-0, +0, e] 
void lual openlibs (lua State *L); 
打开 指定 状态 机 中 的 所 有 Lua 标准 库 。 
lual_ optinteger 


[-0, +0, V] 


lua_Integer lual_optinteger (Lua_State *L, 
int arg, 
lJua_Integer d); 


如 果 画 数 的 第 arg 个 参数 是 一 个 整数 (或 可 以 转换 为 一 个 整数 ) ， 返回 该 整数 。 若 该 参数 
不 存在 或 是 nil， 返回 d 。 除 此 之 外 的 情况 ， 抛 出 错误 。 


lual_ optlstring 
[-0, +0, v] 


const char *lual_optlstring (Jua State *L, 
int arg, 
const char *d, 
size t *1); 


如 果 函 数 的 第 arg 个 参数 是 一 个 字符 串 ， 返 回 该 字符 串 。 若 该 参数 不 存在 或 是 nil， 返回 
d 。 除 此 之 外 的 情况 ， 抛 出 错误 。 


若 1 不 为 NULL ， 将 结果 的 长 度 填 入 *1 。 
lualL optnumber 
[-0, +0, v] 


lua_Number JuaL_optnumber (lua_ State *L, int arg, lua_ Number d); 


如 果 函 数 的 第 arg 个 参数 是 一 个 数字 ， 返 回 该 数字 。 若 该 参数 不 存在 或 是 nil， 返回 d 。 
除 此 之 外 的 情况 ， 抛 出 错误 。 


lual_optstring 
[-0, +0, v] 


const char *lual_optstring (lua_ State *L, 
int arg, 
const char *d); 


如 果 函 数 的 第 arg 个 参数 是 一 个 字符 串 ， 返 回 该 字符 串 。 若 该 参数 不 存在 或 是 nil， 返回 
d 。 除 此 之 外 的 情况 ， 抛 出 错误 。 


lual prepbuffer 


[-?, +?, €] 


char *]luaL_prepbuffer (LuaL_Buffer *B); 


等 价 于 lual prepbuffsize ， 其 预定 义 大 小 为 LUAL BUFFERSIZE 。 
lual prepbuffsize 
[-?, +?, 6] 


char *]luaLlL_prepbuffsize (LuaL_Buffer *B, size _t sz); 


返回 一 段 大 小 为 sz 的 空间 地 址 。 你 可 以 将 字符 串 复 制 其 中 以 加 到 缓存 B 内 (参见 
luaL_Buffer ) 。 将 字符 串 复制 其 中 后 ， 你 必须 调用 lualL_addsize 传人 字符 串 的 大 小 ， 才 
会 真正 把 它 加 入 缓存 。 


lualL_ pushresult 
[-?, +1, 6] 

void JuaL_pushresult (lual_Buffer *B); 
结束 对 缓存 B 的 使 用 ， 将 最 终 的 字符 串 留 在 栈 顶 。 
1LuaL_pushresultsize 
[-?, +1, 6] 

void lual_pushresultsize (lual Buffer *B, size t sz); 
等 价 于 luaL addsize , ' Jual pushresult 。 


lual ref 
[-1, +0, e] 


int lual_ref (lua State *L, int t); 


针对 栈 顶 的 对 象 ， 创 建 并 返回 一 个 在 素 引 t 指向 的 表 中 的 引用 (最 后 会 弹出 栈 顶 对 象 )。 


此 引用 是 一 个 唯一 的 整数 键 。 只 要 你 不 向 表 t 手工 添加 整数 键 ， lual_ref 可 以 保证 它 返 
回 的 键 的 唯一 性 。 你 可 以 通过 调用 lua_rawgeti(L, t, r) 来 找 回 由 r 引用 的 对 象 。 郴 数 
luaL_unref 用 来 释放 一 个 引用 关联 的 对 象 


如 果 栈 顶 的 对 象 是 nil， lualL_ref 将 返回 常量 LuA_REFNIL 。 常量 LUA NOREF 可 以 保证 和 
luaLlL_ref 能 返 反 回 的 其 它 引用 值 不 同 。 


lual_ Reg 


typedef struct lual Reg { 
const char *name; 
Jua_ CFunction func; 

} lual_Reg; 


用 于 1lualL_setfuncs 注册 函数 的 数组 类 型 。 name 指 函 数 名 ， func 是 函数 指针 。 任何 
luaL_Reg 数组 必须 以 一 对 name 与 func 此 为 NULL 结束 。 


lual requiref 


[-0, +1, e] 


void Jual_requiref (lua State *L, const char *modname, 
Jua_CFunction openf, int glb); 


如 果 modname 不 在 package.loaded 中 ， 则 调用 画 数 openf ， 并 传人 字符 串 modname 。 将 
其 返回 值 置信 package.loaded[modname] 。 这 个 行为 好 似 该 图 数 通 过 require 调用 过 一 样 。 


如 果 glb 为 真 ， 同时 也 讲 模 块 设 到 全 局 变量 modname 里 。 
在 栈 上 留 下 该 模块 的 副本 。 

lual setfuncs 

[-nup, +0, e] 


void Jual_setfuncs (lua_ State *L, const lual_Reg *1, int nup); 


把 数组 1 中 的 所 有 冰 数 (参见 lual Reg ) 注册 到 栈 顶 的 表 中 (该 表 在 可 选 的 上 值 之 下 ， 
见 下 面 的 解说 ) 。 


若 nup 不 为 需 ， 所 有 的 函数 都 共享 nup 个 上 值 。 这 些 值 必须 在 调用 之 前 ， 压 在 表 之 上 。 
这 些 值 在 注册 完毕 后 都 会 从 栈 弹 出 。 


lJual setmetatable 
[-0， +0， 一 


void lual_setmetatable (lua State *L, const char *tname ) ; 


将 注册 表 中 tname 关联 元 表 (参见 lual newmetatable ) 设 为 栈 顶 对 象 的 元 表 。 
LuaL_Sstream 


typedef struct JuUaL_Stream { 
FILE *f; 
Jua CFunction closef; 

} luaLl_Stream; 


标准 输入 输出 库 中 用 到 的 标准 文件 句柄 结构 。 


文件 句柄 实现 为 一 个 完全 用 户 数据 ， 其 元 表 被 称 为 LUA_FILEHANDLE 〈 LUA_FILEHANDLE 是 一 
个 代表 真正 元 表 的 名 字 的 宏 ) o 这 张 元 表 由 标准 输入 输出 库 (参见 luaL_newmetatable ) 创 
建 。 


用 户 数据 必须 以 结构 luaL_stream 开头 ; 此 结构 其 后 可 以 包含 任何 其 它 数据 。 f 域 指向 一 
个 C 数据 流 (如 果 它 为 NuLL 表示 一 个 没有 创建 好 的 句柄 ) 。 closef 域 指向 一 个 在 关闭 
或 回收 该 流 时 需要 调用 的 Lua 辑 数 。 该 本 数 将 收 到 一 个 参数 ， 即 文件 句柄 。 它 需 要 返回 
true (操作 成 功 ) 或 nil 加 错误 消息 〈 出 错 的 时 候 ) 。 一 旦 Lua 调用 过 这 个 域 ， 该 域 的 值 就 
会 修改 为 NuLL 以 提示 这 个 句柄 已 经 被 关闭 了 。 


lual testudata 
[-0, +0, e] 


void *lual_ testudata (lua State *L, int arg, const char *tname ) ; 


此 函数 和 1luaL_checkudata 类 似 。 但 它 在 测试 失败 时 会 返回 NuLL 而 不 是 抛 出 错误 。 
lual tolstring 
[-0, +1, e] 
const char *luaL_tolstring (lua State *L, int idx, size t *len); 
将 给 定 索 引 处 的 Lua 值 转换 为 一 个 相应 格式 的 C 字符 串 。 结果 捉 不 仅 会 太 栈 ， 还 会 由 辑 数 返 
回 。 如 果 len 不 为 NULL ， 它 还 把 字符 串 长 度 设 到 *1len 中 。 


如 果 该 值 有 一 个 带 "_ tostring" 域 的 元 表 ， 1luaL_tolstring 会 以 该 值 为 参数 去 调用 对 应 的 
元 方法 ， 并 将 其 返回 值 作为 结果 。 


lual traceback 


[-0, +1, e] 


void JuaL_traceback (1Lua_State *L, lua State *L1, const char *msg, 
int level); 


将 栈 L1 的 栈 回 溯 信 息 压 栈 。 如 果 msg 不 为 NULL ， 它 会 附加 到 栈 回溯 信息 之 前 。 
level 参数 指 明 从 第 几 层 开始 做 栈 回 漳 。 


lual_ typename 
[-0, +0, 一 
const char *lual_ typename (lua_ State *L, int index); 
返回 给 定 索 引 处 值 的 类 型 名 。 
lualL unref 
[-0, +0, 一 


void JuaL_unref (lua State *L, int t, int ref); 


释放 索引 t 处 表 的 ref 引用 对 象 (参见 lualL_ref ) 。 此 条 目 会 从 表 中 移 除 以 让 其 引用 


的 对 象 可 被 垃圾 收集 。 而 引用 ref 也 被 回收 再 次 使 用 。 


如 果 ref 为 LUA NOREF 或 LUA REFNIL ， luaL_unref 什么 也 不 做 。 


lual _ where 


[-0, +1, e] 


void lual where (lua State *L, int lv]1); 


将 一 个 用 于 表示 1v1 层 栈 的 控制 点 位 置 的 字符 串 压 栈 。 这 个 字符 串 遵循 下 面 的 格式 : 


_chunkname_:_currentline : 


0 层 指 当 前 正在 运行 的 事 数 ， 1 层 指 调用 正在 运行 画 数 的 函数 ， 依次 类 推 。 


这 个 画 数 用 于 构建 错误 消息 的 前 级 。 


6 一 标准 库 


标准 库 提供 了 一 些 有 用 的 函数 , 它们 都 是 直接 用 C API 实现 的 。 其 中 一 些 函 数 提 供 了 原本 语 
言 就 有 的 服务 (例如 ， type 与 getmetatable ) 另 一 些 提供 和 ‘外 部 "打交道 的 服务 (例如 
MO ) ; 还 有 些 本 可 以 用 Lua 本 身 来 实现 ， 但 在 C 中 实现 可 以 满足 关键 点 上 的 性 能 需求 ( 例 


如 table. sort ) 3 


所 有 的 库 都 是 直接 用 C API 实现 的 ， 并 以 分 离 的 C 模块 形式 提供 。 目前 ，Lua 有 下 列 标准 


。 基础 库 (S6.1); 

。 协 程 库 ($6.2); 

。 包 管 理 库 (§6.3); 

。 字符 串 控制 (86.4); 

。 基础 UTF-8 支持 (86.5); 

。 表 控 制 (86.6); 

。 数学 函数 ($6.7) (sin ，log 等 ); 
。 输入 输出 (36.8); 

。 操作 系统 库 (86.9); 

。 调试 库 (86.10). 


除了 基础 库 和 包 管 理 库 ， 其 它 库 都 把 自己 的 函数 放 在 一 张 全 局 表 的 域 中 ， 或 是 以 对 象 方法 的 
形式 提供 。 


要 使 用 这 些 库 ， C 的 宿主 程序 需要 先 调用 一 下 _ 1luaL_openlibs 这 个 函数 ， 这 样 就 能 打开 所 有 
的 标准 库 。 或 者 宿主 程序 也 可 以 用 1ual requiref 分 别 打 开 这 些 库 : Iluaopen_base (基础 
库 ) ， luaopen_package 【〈 包 管理 库 ) ， 1luaopen_coroutine  ( 协 程 库 ) ， luaopen_string 
(字符 串 库 ) ， luaopen_utf8 (UTF8 库 ) ， luaopen_table 【( 表 处 理 库 ) ， 

luaopen_math (数学 库 ) ， luaopen io (Il/O 库 ) ， luaopen_ os (操作 系统 库 ) ， 
luaopen_debug (调试 库 ) 。 这 些 范 数 都 定义 在 lualib.n 中 。 


6.1 -- 基础 函数 


as Lua 核心 画 数 。 如 果 你 不 将 这 个 库 包含 在 你 的 程序 中 ， 你 就 需要 小 心 检 查 程 序 
否 需 要 自己 提供 其 中 一 些 特性 的 实现 。 


assert (v [, message]) 


如 果 其 参数 v 的 值 为 假 (nil 或 false) ， 它 就 调用 error ; 否则 ， 返 回 所 有 的 参数 。 在 
错误 情况 时 ， message 指 那个 错误 对 象 ; 如 果 不 提供 这 个 参数 ， 参 数 默认 为 


”assertion failedl 


collectgarbage ([opt [, arg]]) 


这 个 函数 是 垃圾 收集 器 的 通用 接口 。 通过 参数 opt 它 提供 了 一 组 不 同 的 功能 : 


collect ": 做 一 次 完整 的 垃圾 收集 循环 。 这 是 默认 选项 。 

"” stop": 停止 垃圾 收集 器 的 运行 。 在 调用 重启 前 ， 收 集 器 只 会 因 显 式 的 调用 运行 。 

。 "restart ": 重启 垃圾 收集 器 的 自动 运行 。 

”count ": 以 K 字 节 数 为 单位 返回 Lua 使 用 的 总 内 存 数 。 这 个 值 有 小 数 部 分 ， 所 以 只 需 

要 乘 上 1024 就 能 得 到 Lua 使 用 的 准确 字 节 数 ( 除 非 浴 出 ) 。 

e " step ": 单 步 运行 垃圾 收集 器 。 步 长 “大 小 ”由 arg 控制 。 传 入 0 时 ， 收 集 器 步 进 (不 
可 分 割 的 ) 一 步 。 传 入 非 0 值 ， 收集 器 收集 相当 于 Lua 分 配 这 些 多 (K 字 节 ) 内 存 的 工 
作 。 如 果 收 集 器 结束 一 个 循环 将 返回 true 。 

e。 "setpause ": 将 arg 设 为 收集 器 的 间歇 率 (参见 $2.5) 。 返回 间歇 率 的 前 一 个 值 。 

"setstepmul ": 将 arg 设 为 收集 器 的 步 进 倍率 (参见 82.5) 。 返回 步 进 倍率 的 前 一 

个 值 。 

。 "isrunning ": 返回 表示 收集 器 是 否 在 工作 的 布尔 值 〈 即 未 被 停止 ) 。 


dofile ([filename]) 


打开 该 名 字 的 文件 ， 并 执行 文件 中 的 Lua 代码 块 。 不 带 参数 调用 时 ， dofile 执行 标准 输入 
的 内 容 〈 stdin ) 。 返回 该 代码 块 的 所 有 返回 值 。 对 于 有 错误 的 情况 ， dofile 将 错误 反馈 
给 调用 者 ( 即 ， dofile 没有 运行 在 保护 模式 下 ) 。 


error (message [, levell]) 


中 止 上 一 次 保 折 男 数 调用 ， 将 错误 对 象 message 返回 。 画 数 error 永远 不 会 返回 。 


当 message 是 一 个 字符 串 时 ， 通 常 error 会 把 一 些 有 关 出 错位 置 的 信息 附加 在 消息 的 前 
头 。 level 参数 指明 了 怎样 获得 出 错位 置 。 对 于 level 1 (默认 值 ) ， 出 错位 置 指 error 
函数 调用 的 位 置 。 Level 2 将 出 错位 置 指向 调用 error 的 函数 的 函数 ; 以 此 类 推 。 传 入 level 
0 可 以 避免 在 消息 前 添加 出 错位 置信 息 。 


6 


一 个 全 局 变量 ( 非 函 数 ) ， 内 部 储存 有 全 局 环境 (参见 $2.2) 。 Lua 自己 不 使 用 这 个 变量 ; 
改变 这 个 变量 的 值 不 会 对 任何 环境 造成 影响 ， 反 之 亦 然 。 


getmetatable (object) 


如 果 object 不 包含 元 表 ， 返 回 nil 。 否则 ， 如 果 在 该 对 象 的 元 表 中 有 "_metatable" 域 时 
返回 其 关联 值 ， 没有 时 返回 该 对 象 的 元 表 。 
ipairs (t) 


返回 三 个 值 《和 迭代 画 数 、 表 t 以 及 0 ) ， 如 此 ， 以 下 代码 


for i,v in ipairs(t) do _body_ end 


将 迭代 键 值 对 ( 1,t[1] )，( 2,t[2] )，... ， 直 到 第 一 个 空 值 。 


load (chunk [, chunkname [, mode [, env]]1]) 


加 载 一 个 代码 块 。 


如 果 chunk 是 一 个 字符 串 ， 代 码 块 指 这 个 字符 串 。 如 果 chunk 是 一 个 函数 ， load 不 断 地 
调用 它 获取 代码 块 的 片断 。 每 次 对 chunk 的 调用 都 必须 返回 一 个 字符 串 紧 紧 连 接 在 上 次 调 
用 的 返回 串 之 后 。 当 返 回 空 串 、nil、 或 是 不 返回 值 时 ， 都 表示 代码 块 结束 。 


如 果 没 有 语法 错 错误 ， 则 以 男 半数 形式 返回 编译 好 的 代码 块 ; 否则 ， 返 回 nil 加 上 错 误 消 息 


如 果 结 果 画 数 有 上 值 ， env 被 设 为 第 一 个 上 值 。 若 不 提供 此 参数 ， 将 全 局 环境 替代 它 。 所 
有 其 它 上 值 初始 化 为 nil。 《〈 当 你 加 载 主 代 码 块 时 候 ， 结 果 画 数 一 定 有 且 仅 有 一 个 上 值 _ENV 
(参见 S2. 2) ) 。 然而 ， 如 果 你 加 载 一 个 用 函数 (参见 string.dump ， 结果 回 9 数 可 以 有 任意 
数量 的 上 值 ) 创建 出 来 的 二 进 制 代 码 块 时 ， 所 有 的 上 值 都 是 新 创建 出 来 的 。 也 就 是 说 它们 不 
会 和 别 的 任何 画 数 共享 。 


chunkname 在 错误 消 息 和 调试 消息 中 (参见 S4.9) 9 用 于 代码 块 的 名 字 。 如 果 不 提供 此 参 
数 ， 它 默认 为 字符 串 cnunk 。 chunk 不 是 字符 串 时 ， 则 为 ”=(load) "。 


字符 串 mode Re ei 二 进 制 ( 即 预 编译 代码 块 ) 。 它 可 以 是 字符 串 " p" 
(只 能 是 二 进 制 代码 块 ) ，" t ”只 有 Fp ， 或 " pt ”( 可 以 是 二 进 制 也 可 以 
是 文本 ) 。 默认 值 为 " pt "。 


Lua 不 会 对 二 进 制 代码 块 做 健壮 性 检查 。 悉 意 构造 一 个 二 进 制 块 有 可 能 把 解释 器 弄 月 渍 。 
loadfile ([filename [, mode [, env]]]) 


和 load 类 似 ， 不 过 是 从 文件 filename 或 标准 输入 〈 如 果 文 件 名 未 提供 ) 中 获取 代码 块 。 


next (table [, index]) 


运行 程序 来 舱 历 表 中 的 所 有 域 。 第 一 个 参数 是 要 通 历 的 表 ， 第 二 个 参数 是 表 中 的 某 个 键 。 
next 返回 该 键 的 下 一 个 键 及 其 关联 的 值 。 如 果 用 nil 作为 第 二 个 参数 调用 next 将 返回 初 
始 键 及 其 关联 值 。 当 以 最 后 一 个 键 去 调用 ， 或 是 以 nil 调用 一 张 空 表 时 ， next 返回 nil。 
如 果 不 提供 第 二 个 参数 ， 将 认为 它 就 是 nil。 特别 指出 ， 你 可 以 用 next(t) 来 判断 一 张 表 是 


否 是 空 的 。 


索引 在 表 历 过 程 中 的 次 序 无 定义 ， 即使 是 数字 索引 也 是 这 样 。 如 果 想 按 数 字 次 序 表 万 表 ， 
可 以 使 用 数字 形式 的 for 。) 


当 在 通 历 过 程 中 你 给 表 中 并 不 存在 的 域 赋值 ， next 的 行为 是 未 定义 的 。 然而 你 可 以 去 修改 
那些 已 存在 的 域 。 特别 指出 ， 你 可 以 清除 一 些 已 存在 的 域 。 


pairs (t) 
如 果 t 有 元 方法 _pairs ， 以 t 为 参数 调用 它 ， 并 返回 其 返回 的 前 三 个 值 。 
否则 ， 返 回 三 个 值 : next 加 数 ， 表 t ， 以 及 nil。 因此 以 下 代码 


for k,v in pairs(t) do _body_ end 


能 迭代 表 t 中 的 所 有 键 值 对 。 
参见 函数 next 中 关于 迭代 过 程 中 修改 表 的 风险 。 
pcall (f [, arg1i, :::]) 


传人 参数 ， 以 保护 模式 调用 函数 f 。 这 意味 着 f 中 的 任何 错误 不 会 抛 出 ; 取而代之 的 
是 ， pcall 会 将 错误 捕获 到 ， 并 返回 一 个 状态 码 。 第 一 个 返回 值 是 状态 码 〈 一 个 布尔 量 ) ， 
当 没 有 错误 时 ， 其 为 真 。 此 时 ， pcall 同样 会 在 状态 码 后 返回 所 有 调用 的 结果 。 在 有 错误 
时 ， pcall 返回 false 加 错误 消息 。 


print (:::) 


接收 任意 数量 的 参数 ， 并 将 它们 的 值 打印 到 stdout 。 它 用 tostring 加 数 将 每 个 参数 都 转 
换 为 字符 串 。 print 不 用 于 做 格式 化 输出 。 仅 作为 看 一 下 某 个 值 的 快捷 方式 。 多 用 于 调 
试 。 完整 的 对 输出 的 控制 ， 请 使 用 string.format 以 及 io.write 。 

rawequal (vi, v2) 


在 不 触发 任何 元 方法 的 情况 下 检查 vi 是否 和 v2 相等 。 返回 一 个 布尔 量 。 


rawget (table, index) 


在 不 触发 任何 元 方法 的 情况 下 获取 table[index] 的 值 。 table 必须 是 一 张 表 ; index 可 
以 是 任何 值 。 


rawlen (v) 


在 不 触发 任何 元 方法 的 情况 下 返回 对 象 v 的 长 度 。 v 可 以 是 表 或 字符 串 。 它 返回 一 个 整 
数 。 


rawset (table, index, value) 


在 不 触发 任何 元 方法 的 情况 下 将 table[index] 设 为 value 。 table 必须 是 一 张 表 ， 
index 可 以 是 nil 与 NaN 之 外 的 任何 值 。 value 可 以 是 任何 Lua 值 。 


这 个 本 数 返回 table 。 


select (index, ::.:) 


如 果 index 是 个 数字 ， 那么 返回 参数 中 第 index 个 之 后 的 部 分 ; 负 的 数字 会 从 后 向 前 索 
引 (-1 指 最 后 一 个 参数 ) 。 否则 ， index 必须 是 字符 串 "#" ， 此 时 select 返回 参数 的 个 
数 。 


setmetatable (table, metatable) 


给 指定 表 设 置 元 表 。 (你 不 能 在 Lua 中 改变 其 它 类 型 值 的 元 表 ， 那 些 只 能 在 C 里 做 。) 如 
果 metatable 是 nil, 将 指定 表 的 元 表 移 除 。 如 果 原 来 那 张 元 表 有 "_ metatable" 域 ， 抛 出 


一 个 错误 。 


这 个 回 数 返回 table 。 


tonumber (e [, basel]) 

如 果 调 用 的 时 候 没 有 base ， tonumber 尝试 把 参数 转换 为 一 个 数字 。 如 果 参 数 已 经 是 一 个 
数字 ， 或 是 一 个 可 以 转换 为 数字 的 字符 串 ， tonumber 就 返回 这 个 数字 ; 否则 返回 nil。 
字符 串 的 转换 结果 可 能 是 整数 也 可 能 是 浮 点 数 ， 这 取决 于 Lua 的 转换 文法 (参见 83.1) 。 
(字符 串 可 以 有 前 置 和 后 置 的 空格 ， 可 以 带 符号 。) 


当 传 人 base 调用 它 时 ， e 必须 是 一 个 以 该 进 制 表示 的 整数 字符 串 。 进 制 可 以 是 2 到 36 
(包含 2 和 36) 之 间 的 任何 整数 。 大 于 10 进 制 时 ， 字 母 "' A ' (大 小 写 均 可 ) 表示 10 ， 

' B' 表示 11， 依 次 到 ' z ' 表示 35 。 如 果 字 符 串 e 不 是 该 进 制 下 的 合法 数字 ， 画 数 返回 

nil。 


tostring (v) 


可 以 接收 任何 类 型 ， 它 将 其 转换 为 人 可 阅读 的 字符 串 形 式 。 浮 点 数 总 被 转换 为 浮 点 数 的 表现 
形式 (小 数 点 形式 或 是 指数 形式 ) 。 (如 果 想 完全 控制 数字 如 何 被 转换 ， 可 以 使 用 


Semmngeionmate, ) 


如 果 v 有 "_ tostring" 域 的 元 表 ， tostring 会 以 v 为 参数 调用 它 。 并 用 它 的 结果 作 
为 返回 值 。 


type (V) 
将 参数 的 类 型 编码 为 一 个 字符 串 返 回 。 丽 数 可 能 的 返回 值 上 有 "nil " (一 个 字符 串 ， 而 不 是 


nil 值 ) ， "number "， string "， ”boolean ", table "， " function ", 


userdata 。 


" thread "， 


_VERSION 
一 个 包含 有 当前 解释 器 版 本 号 的 全 局 变量 (并非 函数 ) 。 当前 这 个 变量 的 值 为 " Lua 5.3 "。 
xpcall (f, msgh [, arg1i, :..:]) 


这 个 西数 和 pcall 类 似 。 不 过 它 可 以 额外 设置 一 个 消息 处 理 器 msgh O 


6.2 -- 协 程 管理 


关于 协 程 的 操作 作为 基础 库 的 一 个 子 库 ， 被 放 在 一 个 独立 表 coroutine 中 。 协 程 的 介绍 参 
见 $2.6 。 


coroutine .create (f) 


创建 一 个 主体 函数 为 f 的 新 协 程 。 f 必须 是 一 个 Lua 的 函数 。 返回 这 个 新 协 程 ， 它 是 一 
个 类 型 为 "thread" 的 对 象 。 


coroutine.isyieldable () 
如 果 正 在 运行 的 协 程 可 以 让 出 ， 则 返回 真 。 
不 在 主线 程 中 或 不 在 一 个 无 法 让 出 的 C 画 数 中 时 ， 当 前 协 程 是 可 让 出 的 。 


coroutine.resume (co [, val1i, ...]) 


开始 或 继续 协 程 co 的 运行 。 当 你 第 一 次 延续 一 个 协 程 ， 它 会 从 主体 画 数 处 开始 运行 。 
vall , ... 这 些 值 会 以 参数 形式 传人 主体 函数 。 sw ia resume 会 重新 启动 它 ; 
vall , .… 这 些 参数 会 作为 让 出 点 的 返回 值 。 


如 果 协 程 运行 起 来 没有 错误 ， resume 返回 true 加 上 传 给 yield 0 ( 当 协 程 让 
出 ) ， 或 是 主体 函数 的 所 有 返回 值 〈 当 协 程 中 止 ) 。 如 果 有 任何 错误 发 resume 返回 
false 加 错误 消息 。 


coroutine.running () 
返回 当前 正在 运行 的 协 程 加 一 个 布尔 量 。 如 果 当 前 运行 的 协 程 是 主线 程 ， 其 为 真 。 


coroutine.status (co) 


以 字符 串 形 式 返 回 协 程 co 的 状态 : 当 协 程 正 在 运行 〈 它 就 是 调用 status 的 那个 ) ， 返 
回 “running" ; 如 果 协 程 调用 yield nn 返回 "suspended" ; 如 果 
协 程 是 活动 的 ， 都 并 不 在 运行 〈 即 它 正 在 延续 其 它 协 程 ) ， "normal" ; 如 果 协 程 运行 
完 主体 函数 或 因 错 误 停 止 ， 返 回 "dead" 。 


coroutine.wrap (f) 


创建 一 个 主体 函数 为 f 的 新 协 程 。 f 必须 是 一 个 Lua 的 函数 。 返回 一 个 函数 ， 每 次 调用 
该 函数 都 会 延续 该 协 程 。 传 给 这 人 人 resume 1 和 resume 返 
回 相 同 的 值 ， 只 是 没有 第 一 个 布尔 量 。 如 果 发 生 任何 错误 ， 抛 出 这 个 错误 。 


coroutine.yield (.::) 


挂 起 正在 调用 的 协 程 的 执行 。 传递 给 yield 的 参数 都 会 转 为 resume 的 额外 返回 值 。 


6.3 -- 模块 


包 管 理 库 提 供 了 从 Lua 中 加 载 模 块 的 基础 库 。 只 有 一 个 导出 函数 直接 放 在 全 局 环境 中 : 
require 。 所 有 其 它 的 部 分 都 导出 在 表 package 中 。 


require (modname ) 


加 载 一 个 模块 。 这 个 画 数 首先 查找 package.loaded 表 ， 检测 modname 是 否 被 加 载 过 。 如 
果 被 加 载 过 ， require 返回 package.loaded[modnane] 中 保存 的 值 。 否则 ， 它 试 着 为 模块 寻 
找 加 载 器 。 

require 遵循 package.searchers 序列 的 指引 来 查找 加 载 器 。 如 果 改 变 这 个 序列 ， 我 们 可 以 
改变 require 如何 查找 一 个 模块 。 下 列 说 明基 于 package.searchers 的 默认 配置 。 


首先 require 查找 package.preload[modname] 。 如 果 这 里 有 一 个 值 ， 这 个 值 ( 岂 须 是 一 
画 数 ) 就 是 那个 加 载 器 。 否则 require 使 用 Lua 加 载 器 去 查找 package.path 的 路 径 。 
果 查 找 失败 ， 接 着 使 用 C 加 载 器 去 查找 package.cpath 的 路 径 。 如 果 都 失败 了 ， 再 尝试 一 


体 化 加 载 器 (参见 package.searchers ) 。 


每 次 找到 一 个 加 载 器 ， require 都 用 两 个 参数 调用 加 载 器 : modname 和 一 个 在 获取 加 载 器 过 
程 中 得 到 的 参数 。 《如 果 通 过 查找 文件 得 到 的 加 载 器 ， 这 个 额外 参数 是 文件 名 。) 如 果 加 载 
器 返回 非 空 值 ， require 将 这 个 值 赋 给 package.loaded[modname] 。 如 果 加 载 器 没 能 返回 一 
个 非 空 值 用 于 赋 给 package.loaded[modname] ， require 会 在 那里 设 入 true 。 无 论 是 什么 情 


况 ， require 都 会 返回 package.loaded[modname] 的 最 终 值 。 


如 果 在 加 载 或 运行 模块 时 有 错误 ， 或 是 无 法 为 模块 找到 加 载 器 ， require 都 会 抛 出 错误 。 
package.config 


一 个 描述 有 一 些 为 包 管理 准 各 的 编译 期 配置 信息 的 串 。 这 个 字符 串 由 一 系列 行 构成 : 


。 第 一 行 是 目录 分 割 串 。 对 于 Windows 默认 是 '、' ， 对 于 其 它 系 统 是 ' /'。 

。 第 二 行 是 用 于 路 径 中 的 分 割 符 。 默 认 值 是 ' ; '。 

。 第 三 行 是 用 于 标记 模板 替换 点 的 字符 串 。 默认 是 '?'。 

。 第 四 行 是 在 Windows 中 将 被 蔡 换 成 执行 程序 所 在 目录 的 路 径 的 字符 串 。 默认 是 ' !'。 
。 第 五 行 是 一 个 记号 ， 该 记号 之 后 的 所 有 文本 将 在 构建 luaopen ” 画 数 名 时 被 忽略 掉 。 加 


认 是 ' Ee 站 
package.cpath 


这 个 路 径 被 require 在 C 加 载 器 中 做 搜索 时 用 到 。 


Lua 用 和 初始 化 Lua 路 径 package.path 相同 的 方式 初始 化 C 路 径 package.cpath 。 它 会 使 
用 环境 变量 LuA_cPATH 5 3 或 环境 变量 LuA_cPATH 初始 化 。 要 么 就 采用 luaconf.h 中 定义 


的 黑 认 路 径 。 
package.loaded 


用 于 require 控制 哪些 模块 已 经 被 加 载 的 表 。 当 你 请 求 一 个 modname 模块 ， 且 
package.1loaded[modname] 不 为 假 时 ， mequirne 简单 返回 储存 在 内 的 值 。 


这 个 变量 仅仅 是 对 真正 那 张 表 的 引用 ; 改变 这 个 值 并 不 会 改变 require 使 用 的 表 。 


package.loadlib (libname, funcname) 
让 宿主 程序 动态 链接 C 库 libname 。 


当 funcname 为 "*"， 它 仅 仅 连 接 该 库 ， 让 库 中 的 符号 都 导出 给 其 它 动 态 链接 库 使 用 。 否 
则 ， 它 查找 库 中 的 函数 funcname ， 以 C 男 数 的 形式 返回 这 个 画 数 。 因此 ， funcname 必须 
遵循 原型 Jua CFunction (参见 lua_CFunction ) 6 


这 是 一 个 低 阶 函数 。 它 完 全 绕 过 了 包 模 块 系统 。 和 require 不同 ， 它 不 会 做 任何 路 径 坦 

询 ， 也 不 会 自 动 加 扩展 名 。 libname 必须 是 一 个 C 库 需 要 的 完整 的 文件 名 ， 如 果 有 必要 ， 需 
要 提供 路 径 和 扩展 名 。 funcname 必须 是 C 库 需要 的 准确 名 字 (这 取决 于 使 用 的 C 编译 器 和 
链接 器 ) 。 

这 个 函数 在 标准 C 中 不 支持 。 因此 ， 它 只 在 部 分 平台 有 效 ( Windows，Linux ，Mac OS X， 
Solaris, BSD, 加 上 支持 dlfcn 标准 的 Unix 系统 ) 。 


package.path 


这 个 路 径 被 require 在 Lua 加 载 器 中 做 搜索 时 用 到 。 
在 启动 时 ，Lua 用 环境 变量 LUA PATH_5 3 或 环境 变量 LuA_pPATH 来 初始 化 这 个 变量 。 或 采 
用 luaconf.n 中 的 默认 路 径 。 环境 变量 中 出 现 的 所 有 " ;; "都 会 被 奉 换 成 默认 路 径 。 


package.preload 
保存 有 一 些 特殊 模块 的 加 载 器 (参见 require ) 。 
这 个 变量 仅仅 是 对 真正 那 张 表 的 引用 ; 改变 这 个 值 并 不 会 改变 require 使 用 的 表 。 


package.searchers 


用 于 require 控制 如 何 加 载 模块 的 表 。 


这 张 表 内 的 每 一 项 都 是 一 个 查找 器 酌 数 。 当 查 找 一 个 模块 时 ， _ require 按 次 序 调用 这 些 查 

找 器 ， 并 传人 模块 名 ( require 的 参数 ) 作为 唯一 的 一 个 参数 。 此 沙 数 可 以 返回 另 一 个 琅 数 
(模块 的 加 载 器 ) 加 上 另 一 个 将 传递 给 这 个 加 载 器 的 参数 。 或 是 返回 一 个 描述 为 何 没 有 找到 
这 个 模块 的 字符 串 (或 是 返回 nil 什么 也 不 想 说 ) 。 


Lua 用 四 个 查找 器 画 数 初始 化 这 张 表 。 
第 一 个 查找 器 就 是 简单 的 在 package.preload 表 中 查找 加 载 器 。 


第 二 个 查找 器 用 于 查找 Lua 库 的 加 载 库 。 它 使 用 储存 在 package.path 中 的 路 径 来 做 查找 工 
作 。 查找 过 程 和 加 数 package.searchpath 描述 的 一 致 。 


第 三 个 查找 器 用 于 查找 C 库 的 加 载 库 。 它 使 用 储存 在 package.cpath 中 的 路 径 来 做 查找 工 
作 。 同样 ， 查找 过 程 和 函数 package.searchpath 描述 的 一 致 。 例如 ， 如 果 C 路 径 是 这 样 一 
个 字符 串 


"./?.s0;./?.dll;/usr/local/?/init.so" 


查找 器 查找 模块 foo 会 依次 尝试 打开 文件 ./foo.so ， ./foo.d11 ， 以 及 
/usr/local/foo/init.so o 一 旦 它 找 到 一 个 C 库 ， 查找 器 首先 使 用 动态 链接 机 制 连接 该 库 。 
然后 党 试 在 该 库 中 找到 可 以 用 作 加 载 器 的 C 画 数 。 这 个 C 画 数 的 名 字 是 " luaopen " 紧 接 模 

块 名 的 字符 蝇 ， 其 中 字符 串 中 所 有 的 下 划 线 都 会 被 蔡 换 成 点 。 此 外 ， 如 果 模 块 名 中 有 横 线 ， 

横 线 后 面 的 部 分 (包括 横 线 ) 都 被 去 掉 。 例如 ， 如 果 模 块 名 为 a.b.c-v2.1 ， 图 数 名 就 是 


luaopen a b co 


第 四 个 搜索 器 是 ”一体 化 加 载 器 。 它 从 C 路 径 中 查找 指定 模块 的 根 名 字 。 例如 ， 当 请 求 
a.b.c ”时 ， 它 将 查找 a 这 个 C 库 。 如 果 找 得 到 ， 它 会 在 里 面 找 子 模块 的 加 载 男 数 。 在 
我 们 的 例子 中 ， 就 是 找 luaopen a_b c 。 利用 这 文 个 机 制 ， 可 以 把 若干 C 子 模块 打包 进 单 个 
库 。 每 个 子 模块 都 可 以 有 原本 的 加 载 男 数 名 。 


除了 第 一 个 〈 预 加 载 ) 搜索 器 外 ， 每 个 搜索 器 都 会 返回 它 找到 的 模块 的 文件 名 。 这 和 
package.searchpath 的 返回 值 一 样 。 第 一 个 搜索 器 没有 返回 值 。 


package.searchpath (name, path [, sep [, rep]]) 


在 指定 path 中 搜索 指定 的 name 。 


路 径 是 一 个 包含 有 一 系列 以 分 号 分 割 的 模板 构成 的 字符 串 。 对 于 每 个 模板 ， 都 会 用 name 
蔡 换 其 中 的 每 个 问号 〈 如 果 有 的 话 ) 。 且 将 其 中 的 sep (默认 是 点 ) 蔡 换 为 rep (默认 是 
系统 的 目录 分 割 符 ) 。 然后 尝试 打开 这 个 文件 名 。 


例如 ， 如 果 路 径 是 字符 串 


"./?.lua;./?.]lc;/usr/local/?/init.lua" 


搜索 foo.a 这 个 名 字 将 依次 尝试 打开 文件 ./foo/a.lua ， ./foo/a.lc  ， 以 及 


/usr/local/foo/a/init.lua o 


返回 第 一 个 可 以 用 读 模式 打开 (并 马上 关闭 该 文件 ) 的 文件 的 名 字 。 如 果 不 存 在 这 样 的 文 
件 ， 返 回 nil 加 上 错误 消息 。 (这 条 错误 消息 列 出 了 所 有 尝试 打开 的 文件 名 。) 


6.4 一 字 稚 串 人 处 理 


个 库 提 供 了 字符 串 处 理 的 通用 画 数 。 例如 字符 串 查找 、 子 串 、 模 式 匹 配 等 。 当 在 Lua 中 对 
et 第 一 个 字符 从 1 开始 计算 (而 不 是 C 里 的 0) 。 索引 可 以 是 负数 ， 它 指 从 
字符 串 末尾 反 向 解析 。 即 ， 最 后 一 个 字符 在 -1 位 置 人 处 ， 等 等 。 


字符 串 库 中 的 所 有 男 数 都 在 表 string 中 。 它 还 将 其 设置 为 字符 串 元 表 的 _ index 域 。 
此 ， 你 可 以 以 面向 对 象 的 形式 使 用 字符 串 函 打数。 例如 ， string.byte(s,i) 可 以 写成 


s:byte(i) 。 


字符 串 库 假定 采用 单字 节 字 符 编码 。 


string.byte (s [, i [, j]]) 


返回 字符 s[i] ， s[i+1] ，... ， s[j] 的 内 部 数字 编码 。 i 的 默认 值 是 1 ; j 的 默认 
值 是 i 。 这 些 索 引 以 函数 string.sub 的 规则 修正 。 


数字 编码 没有 必要 跨 平台 。 
string.char (:…) 


接收 需 或 更 多 的 整数 。 返回 和 参数 数量 相同 长 度 的 字符 串 。 其 中 每 个 字符 的 内 部 编码 值 等 于 
对 应 的 参数 值 。 


数字 编码 没有 必要 跨 平台 。 
string.dump (function [, strip]) 


返回 包含 有 以 二 进 制 方式 表示 的 (一 个 二 进 制 代码 块 ) 指定 画 数 的 字符 串 。 之 后 可 以 用 
load 调用 这 个 字符 串 获 得 该 函数 的 副本 (但 是 绑 定 新 的 上 值 ) 。 如 果 strip 为 真 值 ， 
二 进 制 代码 块 不 携带 该 画 数 的 调试 信息 (局 部 变量 名 ， 行 号 ， 等 等 。) 。 


带 上 值 的 函数 只 保存 上 值 的 数目 。 当 (再 次 ) 加 载 时 ， 这 些 上 值 被 更 新 为 nil 的 实例 。 (你 
可 以 使 用 调试 库 按 你 需要 的 方式 来 序列 化 上 值 ， 并 重 载 到 画 数 中 ) 
string.find (s, pattern [, init [, plain]]) 


让 s 中 匹配 到 的 ”pattern 见 $S6.4.1) 。 如 果 找 到 一 个 匹配 ， find 会 

返回 s 中 关于 它 起 始 及 终点 位 置 的 素 引 ; 否则 ， 返 回 nil。 第 三 个 可 选 数字 参数 init 指 
明 从 哪里 开始 搜索 ; 默认 值 为 1 ， 同 时 可 以 是 负 值 。 第 四 个 可 选 参数 plain 为 true 时 ， 
关闭 模式 匹配 机 制 。 此 时 函数 仅 做 直接 的 “查找 子 串 "的 操作 ， 而 pattern 中 没有 字符 被 看 
作 魔 法 字符 。 注意 ， 如 果 给 定 了 plain ， 就 必须 写 上 init 。 


如 果 在 模式 中 定义 了 捕获 ， 捕 获 到 的 若干 值 也 会 在 两 个 索引 之 后 返回 。 
string.format (formatstring, :..:) 


返回 不 定数 量 参数 的 格式 化 版 本 ， 格式 化 串 为 第 一 个 参数 (必须 是 一 个 字符 串 ) 。 格式 化 字 
符 串 遵循 ISO C 画 数 sprintf 的 规则 。 不 同 点 在 于 选项 *，h，L，1 ，n，p 不 支持 ， 
另外 还 增加 了 一 个 选项 q 。 9 选项 将 一 个 字符 串 格式 化 为 两 个 双 引 号 括 起 ， 对 内 部 字符 做 
恰当 的 转 义 处 理 的 字符 串 。 该 字符 串 可 以 安全 的 被 Lua 解释 器 读 回 来 。 例如 ， 调 用 


string.format('%q', 'a string with "quotes" and xn new line') 


会 产生 字符 串 : 


"a string with \"quotes\" and \ 
new line" 


选项 A and a (如果 有 的 话 ) ， E ，e ，f ，6 ,and g 都 期 待 一 个 对 应 的 数字 参数 。 
选项 c,， d,i，o,，u,，x,and x 则 期 待 一 个 整数 。 选项 q 期 待 一 个 字符 串 ; 选项 
s 期 待 一 个 没有 内 嵌 需 的 字符 串 。 如 果 选 项 s 对 应 的 参数 不 是 字符 串 ， 它 会 用 和 
tostring 一 致 的 规则 转换 成 字符 串 。 


string.gmatch (s, pattern) 


返回 一 个 迭代 器 函数 。 每 次 调用 这 个 函数 都 会 继续 以 _ pattern (人 参见” 86.4.1) 对 s 做 匹 
配 ， 并 返回 所 有 捕获 到 的 值 。 如 果 pattern 中 没有 指定 捕获 ， 则 每 次 捕获 整个 pattern 。 


下 面 这 个 例子 会 循环 迭代 字符 串 s 中 所 有 的 单词 ， 并 逐 行 打印 : 


S = "hello world from Lua" 

for w in string.gmatch(s, "%a+") do 
print(w) 

end 


下 一 个 例子 从 指定 的 字符 串 中 收集 所 有 的 键 值 对 key=value 置 入 一 张 表 : 


tf 

S = "from=world, to=Lua" 

for k, v in string.gmatch(s, "(%w+)=(%w+)") do 
t[k] = V 

end 


对 这 个 函数 来 说 ， 模 板 前 开始 的 " ^ ' 不 会 当成 锚 点 。 因 为 这 样 会 阻止 迭代 。 
string.gsub (s, pattern, repl [, n]) 


将 字符 串 中， 所 有 的 (或 是 在 n 给 出 时 的 前 n 个 ) ”pattern (参见 86.4.1) 都 替换 
成 repl ， 并 返回 其 副本 。 repl 可 以 是 字符 串 、 表 、 或 画 数 。 gsub 还 会 在 第 二 个 返回 值 
返回 一 共 发 生 了 多 少 次 匹配 。 gsub 这 个 名 字 来 源 于 Global SUBstitution 。 


如 果 repl 是 一 个 字符 串 ， 那 么 把 这 个 字符 串 作 为 蔡 换 品 。 字符 % 是 一 个 转 义 符 : repl 
中 的 所 有 形式 为 %d。 的 串 表 示 第 q 个 捕获 到 的 子 串 ，q 可 以 是 1 到 9。 串 we@ 表示 整个 
匹配 。 串 ww% 表示 单个 % 。 


如 果 repl 是 张 表 ， 每 次 匹配 时 都 会 用 第 一 个 捕获 物 作为 键 去 查 这 张 表 。 


如 果 repl 是 个 画 数 ， 则 在 每 次 匹配 发 生 时 都 会 调用 这 个 函数 。 所 有 捕获 到 的 子 串 依次 作为 
参数 传人 。 


任何 情况 下 ， 模 板 中 没有 设 定 捕获 都 看 成 是 捕获 整个 模板 。 


如 果 表 的 查询 结果 或 函数 的 返回 结果 是 一 个 字符 串 或 是 个 数字 ， 都 将 其 作为 替换 用 串 ; 而 在 
返回 false 或 nil 时 不 作 蔡 换 〈 即 保留 匹配 前 的 原始 串 ) 。 


这 里 有 一 些 用 例 : 
x = string.gsub("hello world", "“(%w+)", "%1 %1") 
--> x="hello hello world world" 


x = string.gsub("hello world", "%w+", "%0 %0", 1) 
--> x="hello hello world" 


x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") 
--> x="world hello Lua from" 


x = string.gsub("home = $HOME, User = $USER", "%$(%w+)", os.getenv) 
--> x="home = /home/roberto, user = roberto" 


x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) 
return load(s)() 
end) 
--> X="4+5 = 9" 
local t = {name="lua", version="5.3"} 


x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) 
--> x="]lua-5.3.tar.gz" 


string.len (Ss) 


接收 一 个 字符 串 ， 返 回 其 长 度 。 空 串 "" 的 长 度 为 0 。 内 嵌 需 也 统计 在 内 ， 因 此 
"a\999bc\666" 的 长 度 为 5。 


string.1lower (S) 


接收 一 个 字符 串 ， 将 其 中 的 大 写字 符 都 转 为 小 写 后 返回 其 副本 。 其 它 的 字符 串 不 会 更 改 。 对 
大 写字 符 的 定义 取决 于 当前 的 区 域 设置 


string.match (s, pattern [, init]) 


在 字符 串 s 中 找到 第 一 个 能 用 pattern (参见 86.4.1) 匹配 到 的 部 分 。 交合 作 全 

到 ， match 返回 其 中 的 捕获 物 ; 否则 返回 nil 。 如 果 pattern 中 未 指定 捕获 ， 返回 整个 
pattern 捕获 到 的 串 。 第 三 个 可 选 数字 参数 init 指明 从 哪里 开始 搜索 ; 它 默 认为 1 且 可 
以 是 负数 。 


String.pack (fmt, v1, v2, :...:) 


一 个 打包 了 ( 即 以 二 进 制 形式 序列 化 ) va ，v2 等 值 的 二 进 制 字 符 串 。 字符 串 fmt 为 
人 (参见 86.4.2) 。 


string.packsize (fmt) 


返回 以 指定 格式 用 string.pack 打包 的 字符 串 的 长 度 。 格式 化 字符 串 中 不 可 以 有 变 长 选项 

' s "或 'z (参见 86.4.2) 。 

string.rep (s, n [，sep]) 

返回 n 个 字符 串 s 以 字符 串 sep 为 分 割 符 连 在 一 起 的 字符 串 。 默认 的 sep 值 为 空 字符 
串 〈 即 没有 分 割 符 ) 。 如 果 n 不 是 正 数 则 返回 空 串 。 


string.reverse (s) 


返回 字符 串 s 的 翻转 串 。 


string.sub (s, i [, j]) 


返回 s 的 子 串 ， 该 子 串 从 i 开始 到 j 为 止 ; i 和 j 都 可 以 为 负数 。 如 果 不 给 出 j 
， 就 当 它 是 -1 (和 字符 串 长 度 相同 ) 。 特别 是 ， 调用 string.sub(s,1,j) 可 以 返回 s 的 
长 度 为 j 的 前 缀 串 ， 而 string.sub(s，-i) 返回 长 度 为 i 的 后 级 串 。 


如 果 在 对 负数 索引 转 义 后 i 小 于 1 的话， 就 修正 回 1 。 如 果 j 比 字 符 串 的 长 度 还 大 ， 就 
修正 为 字符 串 长 度 。 如 果 在 修正 之 后 ， i 大 于 j ， 图 数 返回 空 串 。 


string.unpack (fmt, s [, pos]) 


返回 以 格式 fmt (参见 §6.4.2) 打包 在 字符 串 S (参见 string.pack ) 中 的 值 。 选项 
pos (默认 为 1) 标记 了 从 s 中 哪里 开始 读 起 。 读 完 所 有 的 值 后 ， 函 数 返回 s 中 第 一 个 
未 读 字 节 的 位 置 。 


string.upper (Ss) 


接收 一 个 字符 串 ， 将 其 中 的 小 写字 符 都 转 为 大 写 后 返回 其 副本 。 其 它 的 字符 串 不 会 更 改 。 对 
小 写字 符 的 定义 取决 于 当前 的 区 域 设 置 。 


6.4.1 - 匹配 模式 


Lua 中 的 匹配 模式 直接 用 常规 的 字符 串 来 描述 。 它 用 于 模式 匹配 事 数 string.find ， 
string.gmatch ，string.gsub ，string.match 。 这 一 节 表 述 了 这 些 字 符 串 的 语法 及 含义 ( 即 
它 能 匹配 到 什么 ) 。 

字符 类 : 

字符 类 用 于 表示 一 个 字符 集合 。 下 列 组 合 可 用 于 字符 类 : 


e。X: (这 里 x 不 能 是 魔法 字符 ^$()%.[]*+-? 中 的 一 员 ) 表示 字符 x 自身 。 
e。 . : (一 个 点 ) 可 表示 任何 字符 。 


。 %a : 表示 任何 字母 。 

。 %c : 表示 任何 控制 字符 。 

。 x%d : 表示 任何 数字 。 

。 %g : 表示 任何 除 空白 符 外 的 可 打印 字符 。 

。 %l : 表示 所 有 小 写字 母 。 

。 x%p : 表示 所 有 标点 符号 。 

。 %s ;: 表示 所 有 空白 字符 。 

。 %u : 表示 所 有 大 写字 母 。 

。 %‰w : 表示 所 有 字母 及 数字 。 

。 %x : 表示 所 有 16 进 制 数字 符号 。 

。 % x : (这 里 的 X 是 任意 非 字母 或 数字 的 字符 ) 表示 字符 x。 这 是 对 魔法 字符 转 义 的 标 
准 方法 。 所 有 非 字 母 或 数字 的 字符 (包括 所 有 标点 ， 也 包括 非 魔 法 字符 ) 都 可 以 用 前 和 置 
一 个 ' %' 放 在 模式 串 中 表示 自身 。 

e。 [_set_] : 表示 set 中 所 有 字符 的 联合 。 可 以 以 ' - ' 连接 ， 升序 书 写 范围 两 端的 字符 来 
表示 一 个 范围 的 字符 集 。 上 面 提 到 的 % x 形式 也 可 以 在 set 中 使 用 表示 其 中 的 一 个 元 
素 。 其 它 出 现在 set 中 的 字符 则 代表 它们 自己 。 例如 ， [%w_] (或 [_w%w] ) 表示 所 有 
的 字母 数字 加 下 划 线 ) ， [6-7] 表示 8 进 制 数字 ， [6-7%1%-] ”表示 8 进 制 数 字 加 小 
写字 母 与 ' -' 字符 。 


交叉 使 用 类 和 范围 的 行为 未 定义 。 因此 , 像 [wa-z] 或 [a-x%] 这 样 的 模式 串 没有 意 
义 。 


。 [^_set_] : 表示 set 的 补 集 ， 其 中 set 如 上 面 的 解释 。 


所 有 单个 字母 表示 的 类 别 ( wa ， %c ， 等 ) ， 若 将 其 字母 改 为 大 写 ， 均 表示 对 应 的 补 集 。 
例如 ， xs 表示 所 有 非 空 格 的 字符 。 


如 何 定义 字母 、 空 格 、 或 是 其 他 字符 组 取决 于 当前 的 区 域 设置 。 特别 注意 : [a-z] ”未必 等 
价 于 %1 。 

模式 条 目 : 

模式 条 目 可 以 是 


。 单个 字符 类 匹配 该 类 别 中 任意 单个 字符 ; 
。 单个 字符 类 跟 一 个 " * '， 将 匹配 需 或 多 个 该 类 的 字符 。 这 个 条 目 总 是 匹配 尽 可 能 长 的 


串 ; 

。 单个 字符 类 跟 一 个 '+ '， 将 匹配 一 或 更 多 个 该 类 的 字符 。 这 个 条 目 总 是 匹配 尽 可 能 长 的 
串 ; 

。 单个 字符 类 跟 一 个 ' - '， 将 匹配 老 或 更 多 个 该 类 的 字符 。 和 ' * ' 不同 ， 这 个 条 目 总 是 


匹配 尽 可 能 短 的 串 ; 
。 单个 字符 类 跟 一 个 "* '， 将 匹配 雳 或 一 个 该 类 的 字符 。 只 要 有 可 能 ， 它 会 匹配 一 个 ; 
。 %n ， 这 里 的 n 可 以 从 1 到 9; 这 个 条 目 匹 配 一 个 等 于 n 号 捕获 物 (后 面 有 描述 ) 的 


子 串 。 

。 %b_xy ， 这 里 的 x 和 yy 是 两 个 明确 的 字符 ; 这 个 条 目 匹 配 以 X 开始 y 结束 ， 且 其 中 x 
和 y 保持 平衡 的 字符 串 。 意思 是 ， 如 果 从 左 到 右 读 这 个 字符 串 ， 对 每 次 读 到 一 个 X 就 
+1 ， 读 到 一 个 y 就 -1， 最 终结 束 处 的 那个 y 是 第 一 个 记 数 到 0 的 ww ，” 举 个 例子 ， 条 和 目 

%b() 可 以 匹配 到 括号 平衡 的 表达 式 。 

e。 %f[_set_] ， 指 边境 模式 ; 这 个 条 目 会 匹配 到 一 个 位 于 set 内 某 个 字符 之 前 的 一 个 空 
串 ， 且 这 个 位 置 的 前 一 个 字符 不 属于 set 。 集合 set 的 含义 如 前 面 所 述 。 匹配 出 的 那个 
空 串 之 开始 和 结束 点 的 计算 就 看 成 该 处 有 个 字符 ' \@ ' 一 样 。 


模式 : 
模式 指 一 个 模式 条 目的 序列 。 在 模式 最 前 面 加 上 符号 ' ^ ' 将 锚 定 从 字符 串 的 开始 处 做 匹配 。 


在 模式 最 后 面 加 上 符号 ' $ ' 将 使 匹配 过 程 锚 定 到 字符 串 的 结尾 。 如 果 ' ^' 和 ' $ ' 出 现在 其 
它 位 置 ， 它 们 均 没有 特殊 含义 ， 只 表示 自身 。 


捕获 : 


模式 可 以 在 内 部 用 小 括号 括 起 一 个 子 模式 ; 这 些 子 模式 被 称 为 捕获 物 。 当 匹 配 成 功 时 ， 由 
捕获 物 匹配 到 的 字符 串 中 的 子 串 被 保存 起 来 用 于 未 来 的 用 途 。 捕获 物 以 它们 左 括号 的 次 序 来 
编号 。 例如 ， 对 于 模式 "(a*(.)x%w(%s*))"” ， 字符 串 中 匹配 到 "as*(.)xw(%s*)"” 的 部 分 保存 在 
第 一 个 捕获 物 中 (因此 是 编号 1) ; 由 "”. "匹配 到 的 字符 是 2 号 捕获 物 ， 匹配 到 ”"%s* " 
的 那 部 分 是 3 号 。 


作为 一 个 特例 ， 空 的 捕获 () 将 捕获 到 当前 字符 串 的 位 置 〈 它 是 一 个 数字 ) 。 例如 ， 如 果 将 
模式 "()aa()"” 作用 到 字符 串 "flaaap" 上 ， 将 产生 两 个 捕获 物 : 3 和 5。 


6.4.2 - 打包 和 解 包 用 到 的 格式 串 


用 于 SngRDacke， string.packsize ,, string.unpack 的 第 一 个 参数 。 它 是 一 个 描述 了 需 


要 创建 或 读 取 的 结构 之 布局 。 
格式 串 是 由 转换 选项 构成 的 序列 。 这 些 转换 选项 列 在 后 面 : 


。 &lt; : 设 为 小 端 编码 

。 &gt; : 设 为 大 端 编码 

。 = : 大 小 端 遵循 本 地 设置 

。 ![_n_] :将 最 大 对 齐 数 设 为 n (默认 遵循 本 地 对 齐 设置 ) 
b : 一 个 有 符号 字 节 ( char ) 

。 B : 一 个 无 符号 字 节 ( char ) 
h : 一 个 有 符号 short (本 地 大 小 ) 

e。 H :一 个 无 符号 short (本 地 大 小 ) 

。 1 :一 个 有 符号 long (本 地 大 小 ) 

。 L :一 个 无 符号 1long (本 地 大 小 ) 


© By :== lua_Integer 

se 国 B: 一 个 Jua_Unsigned 

。 T :一 个 size t (本 地 大 小 ) 

e。 i[_n] :一 个 mn 字 节 长 (默认 为 本 地 大 小 ) 的 有 符号 int 

。 I[n] :一 个 n 字 节 长 (默认 为 本 地 大 小 ) 的 无 符号 int 

e。 f :一 个 float (本 地 大 小 ) 

e。 d :一 个 double (本 地 大 小 ) 

e n :一 个 lua_Number 

© Pena: in 字 节 固定 长 度 的 字符 串 

。 z : 需 结 尾 的 字符 串 

。 s[Ln ] :长 度 加 内 容 的 字符 串 ， 其 长 度 编码 为 一 个 n 字 节 (默认 是 个 sizet ) 长 的 

无 符号 整数 。 

。 x : 一 个 字 节 的 填充 

。 X_ op : 按 选 项 op 的 方式 对 齐 〈 忽 略 它 的 其 它 方面 ) 的 一 个 空 条 目 

。": (空格 ) 忽略 

〈("”[n_.] "表示 一 个 可 选 的 整数 。) 除 填充 、 空 格 、 配 置 项 〈 选 项 " xx &lt;=&gt;! ") 外 ， 
每 个 选项 都 关联 一 个 参数 (对 于 string.pack ) 或 结果 (对 于 string.unpack ) 。 
对 于 选项 " !Ln "sn "in ""In "n 可 以 是 1 到 16 间 的 整数 。 所 有 的 整数 选项 
都 将 做 浴 出 检查 ; string.pack 检查 提供 的 值 是 否 能 用 指定 的 字 长 表示 ; string.unpack 检 
查 读 出 的 值 能 否 置 入 Lua 整数 中 。 





任何 格式 串 都 假设 有 一 个 "”!1= " 前 级 ， 即 最 大 对 齐 为 1 (无 对 齐 ) 且 采 用 本 地 大 小 端 设置 。 


对 齐 行 为 按 如 下 规则 工作 : 对 每 个 选项 ， 格 式 化 时 都 会 填充 一 些 字 节 直到 数据 从 一 个 特定 偏 
移 处 开始 ， 这 个 位 置 是 该 选项 的 大 小 和 最 大 对 齐 数 中 较 小 的 那个 数 的 倍数 ; 这 个 较 小 值 必须 
是 2 个 整数 次 方 。 选项 " c" 及 "z "不 做 对 齐 处 理 ; 选项 " s " 对 对 齐 遵循 其 开头 的 整数 。 


string.pack 用 需 去 填充 ( string.unpack 则 忽略 它 ) o 


6.5 一 UTF-8 支持 


这 个 库 提供 了 对 UTF-8 编码 的 基础 支持 。 所 有 的 汞 数 都 放 在 表 utfs 中 。 此 库 不 提供 除 编 
码 处 理 之 外 的 任何 Unicode 支持 。 所 有 需要 了 解 字符 含义 的 操作 ， 比 如 字符 分 类 ， 都 不 在 此 
范畴 。 


除非 另 有 说 明 ， 当 一 个 函数 需要 一 个 字 节 位 置 的 参数 时 ， 都 假定 这 个 位 置 要 么 从 字 节 序列 的 
开始 计算 ， 要 么 从 字符 串 长 度 加 一 的 位 置 算 。 和 字符 串 库 一 样 ， 负 的 索引 从 字符 串 末 尾 计 
起 。 


utf8.char (:.:.:) 


接收 需 或 多 个 整数 ， 将 每 个 整数 转换 成 对 应 的 UTF-8 字 节 序列 ， 并 返回 这 些 序列 连接 到 一 起 
的 字符 串 。 


utf8 .charpattern 


用 于 精确 匹配 到 一 个 UTF-8 字 节 序列 的 模式 (是 一 个 字符 串 ， 并 非 函 
数 ) " [\e-\x7F\xc2-\xF4][\x86-\xBF]* "” (参见 86.4.1) 。 它 假定 义理 的 对 象 是 一 个 合法 的 
UTF-8 字符 串 。 


utf8.codes (Ss) 
返回 一 系列 的 值 ， 可 以 让 
for p, c in utf8.codes(s) do _body_ end 


迭代 出 字符 串 s 中 所 有 的 字符 。 这 里 的 p 是 位 置 ( 按 字 节 数 ) 而 c 是 每 个 字符 的 编 
号 。 如 果 处 理 到 一 个 不 合法 的 字 节 序列 ， 将 抛 出 一 个 错误 。 


utf8.codepoint (s [, i [, j]]) 

一 整数 形式 返回 s 中 从 位 置 i 到 j 间 (包括 两 端 所 有 字符 的 编号 。 默认 的 i 为 1 
， 默 认 的 j 为 i 。 如 果 碰 上 不 合法 的 字 节 序列 ， 抛 出 一 个 错误 。 

utf8.len (s [, i [, j]]) 


返回 字符 串 s 中 从 位 置 i 到 j 间 (包括 两 端 ) UTF-8 字符 的 个 数 。 默认 的 i 为 1， 
默认 的 j 为 -1。 如 果 它 找到 任何 不 合法 的 字 节 序列 ， 返回 假 值 加 上 第 一 个 不 合法 字 节 的 位 
置 。 


utf8 .offset (s, n [, i]) 


返回 编码 在 s 中 的 第 n 个 字符 的 开始 位 置 〈 按 字 节 数 ) (从 位 置 i 处 开始 统计 ) 。 负 
n 则 取 在 位 置 i 前 的 字符 。 当 n 是 非 负数 时 ， 上 默认 的 i 是 1， 否则 默认 为 #s + 1。 
因此 ， utf8.offset(s, -n) 取 字 符 串 的 倒数 第 n 个 字符 的 位 置 。 如 果 指 定 的 字符 不 在 其 中 
或 在 结束 点 之 后 ， 画 数 返 回 nil。 


作为 特例 ， 当 n 等 于 0 时 ， 此 男 数 返回 含有 s 第 i 字 节 的 那个 字符 的 开始 位 置 。 


这 个 辑 数 假定 s 是 一 个 合法 的 UTF-8 字符 串 。 


6.6 -- 表 你 理 


这 个 库 提供 了 表 处 理 的 通用 男 数 。 所 有 画 数 都 放 在 表 table 中 。 


记 住 ， 无 论 何 时 ， 若 一 个 操作 需要 取 表 的 长 度 ， 这 张 表 必 须 是 一 个 真 序列 ， 或 是 拥有 _1len 
元 方法 (参见 $3.4.7 ) 。 所 有 的 琅 数 都 忽略 传 入 参数 的 那 张 表 中 的 非 数 字 键 。 


table.concat (list [, sep [, i [, j]]]) 


提供 一 个 列表 ， 其 所 有 元 素 都 是 字符 串 或 数字 ， 返 回 字符 串 
list[i]..sep..list[i+1] ... sep..list[j] 。 sep 的 默认 值 是 空 串 ， i 的 默认 值 是 1， 
j 的 默认 值 是 #1ist 。 如 果 i 比 j 大 ， 返 回 空 串 。 


table.insert (list, [pos,] value) 


在 list 的 位 置 pos 处 插入 元 素 value ， 并 后 移 元 素 
list[pos]，list[pos+1]，..:，1list[#1list] 。 pos 的 默认 值 为 #1ist+1 ， 因此 调用 
table.insert(t,x) 会 业 x 插 在 列表 t 的 末尾 。 


table.move (alil, f, e, t [,a2]) 


将 元 素 从 表 al 移 到 表 a2 。 这 个 函数 做 了 次 等 价 于 后 面 这 个 多 重 赋值 的 等 价 操 作 : 
Eee pa 


f 必须 是 正 数 。 
table.pack (:..:) 


返回 用 所 有 参数 以 键 1,2, 等 填充 的 新 表 ， 并 将 " n" 这 个 域 设 为 参数 的 总 数 。 注意 这 张 返回 
的 表 不 一 定 是 一 个 序列 。 


table.remove (list [, pos]) 


移 除 list 中 pos 位 置 上 的 元 素 ， 并 返回 这 个 被 移 除 的 值 。 当 pos 是 在 1 到 #1ist 之 间 
的 整数 时 ， 它 向 前 移动 元 素 list[pos+1], list[pos+2], :::, list[#1list] 并 删除 元 素 
list[#list] ; 索引 pos 可 以 是 #1ist + 1 ， 或 在 # 要 ist 为 0 时 可 以 是 0 ; 在 这 些 情况 
下 ， 画 数 删 除 元 素 list[pos] 。 


pos 默认 为 #1ist ， 因此 调用 table.remove(1) 将 移 除 表 1 的 最 后 一 个 元 素 。 


table.sort (list [, comp]) 


在 表 内 从 list[1] 到 list[#1ist] 原 地 对 其 世间 元 素 按 指 定 次 序 排序 。 如 果 提 供 了 comp ， 
它 必须 是 一 个 可 以 接收 两 个 列表 内 元 素 为 参数 的 函数 。 当 第 一 个 元 素 需 要 排 在 第 二 个 元 素 之 
前 时 ， 返 回 真 (因此 not comp(1ist[i+1],1ist[i]) 在 排序 结束 后 将 为 真 ) 。 如 果 没 有 提供 
comp ， 将 使 用 标准 Lua 操 作 &lt; 作为 替代 品 。 


排序 算法 并 不 稳定 ; 即 当 两 个 元 素 次 序 相等 时 ， 它 们 在 排序 后 的 相对 位 置 可 能 会 改变 。 
table.unpack (list [, i [, j]]) 
返回 列表 中 的 元 素 。 这 个 画 数 等 价 于 


return 1LIst[i]l]，1ist[i+l]，'…'…，1ist[j] 


i 默认 为 1， j 默认 为 #1ist 。 


6.7 一 数学 函数 


个 库 提 供 了 基本 的 数学 函数 。 所 以 函数 都 放 在 表 math 中 。 注解 有 "integer/float " 的 琅 
ea ) 参数 返回 浮 点 结果 。 圆 整 本 数 
( math.ceil ， mathefioor math.modf ) 在 结果 在 整 和 数 范 围 内 时 返回 整数 ， 否则 返回 浮 点 
数 。 


math.abs (x) 
返回 x 的 绝对 值 。(integer/float) 


math.acos (x) 


返回 x 的 反 余弦 值 (用 弧度 表示 ) 。 


math.asin (x) 


返回 x 的 反正 弦 值 (用 弧度 表示 ) 。 


math.atan (y [, x]) 


返回 y/x 的 反正 切 值 ( 用 弧度 表示 ) 。 它 会 使 用 两 个 参数 的 符号 来 找到 结果 落 在 哪个 象限 
中 。 (即使 xX 为 需 时 ， 也 可 以 正确 的 义理 。 ) 


默认 的 x 是 1， 因此 调用 math.atan(y) 将 返回 y 的 反正 切 值 。 


math.ceil (x) 
返回 不 小 于 x 的 最 小 整数 值 。 


math.cos (x) 


返回 x 的 余弦 (假定 参数 是 弧度 ) 。 


math.deg (x) 


将 角 x 从 弧度 转换 为 角度 。 

math.exp (x) 

返回 e<sup>x</sup> 的 值 ( 。 为 自然 对 数 的 底 ) 。 
math.floor (x) 

返回 不 大 于 x 的 最 大 整数 值 。 

math .fmod (x, y) 

返回 x 除 以 y ， 将 商 向 需 圆 整 后 的 余数 。 (integer/float) 
math.huge 

浮 点 数 HucE_vAL ， 这 个 数 比 任何 数字 值 都 大 。 

math.log (x [，base]) 

返回 以 指定 底 的 x 的 对 数 。 默认 的 base 是 e (因此 此 函数 返回 x 的 自然 对 数 ) 。 
math.max (x, :::) 

返回 参数 中 最 大 的 值 ， 大 小 由 Lua 操作 &lt; 决定 。 (integer/float) 
math.maxinteger 

最 大 值 的 整数 。 

math.min (x, ::..:) 

返回 参数 中 最 小 的 值 ， 大 小 由 Lua 操作 &lt; 决定 。 (integer/float) 
math.mininteger 

最 小 值 的 整数 。 

math.modf (x) 


返回 x 的 整数 部 分 和 小 数 部 分 。 第 二 个 结果 一 定 是 浮 点 数 。 


math .pi 


厅 的 值 。 


math .rad (x) 


将 角 x 从 角度 转换 为 弧度 。 


math.random ([m [, n]]) 


当 不 带 参 数 调 用 时 ， 返回 一 个 /0,1) 区 间 内 一 致 分 布 的 浮 点 伪 随 机 数 。 当 以 两 个 整数 m 与 


n 调用 时 ， math.random 返回 一 个 [m, n] 区 间 内 一 致 分 布 的 整数 伪 随 机 数 。 
是 负数 ， 且 必须 在 Lua 整数 的 表示 范围 内 。) 调用 math.random(n) 等 价 于 


math.random(1,n) 。 


这 个 函数 是 对 C 提供 的 位 随机 数 函 数 的 封装 。 对 其 统计 属性 不 作 担 保 。 
math.randomseed (Xx) 

把 x 设 为 伪 随 机 数 发 生 器 的 “种 子 " : 相同 的 种 子 产生 相同 的 随机 数列 。 
math.sin (x) 

返回 x 的 正弦 值 (假定 参 数 是 弧度 ) 。 


math.sqrt (x) 


返回 x 的 平方 根 。 (你 也 可 以 使 用 乘 方 x^e.5 来 计算 这 个 值 。) 


math.tan (x) 


返回 x 的 正切 值 (假定 参数 是 弧度 ) 。 


math.tointeger (x) 
如 果 x 可 以 转换 为 一 个 整数 ， 返回 该 整数 。 否则 返回 nil。 


math .type (x) 


如 果 x 是 整数 ， 返 回 " integer "， 如 果 它 是 浮 点 数 ， 返 回 " float "， 如 果 x 


返回 nil。 


math.ult (m, n) 


( 值 m-n 不 能 


不 是 数字 ， 


如 果 整 数 m 和 n 以 无 符号 整数 形式 比较 ， m 在 n 之 下 ， 返 回 布尔 真 否 则 返回 假 。 


6.8 一 输入 输出 库 


I/O 库 提供 了 两 套 不 同 风格 的 文件 处 理 接 口 。 第 一 种 风格 使 用 隐 式 的 文件 句柄 ; 它 提供 设置 
默认 输入 文件 及 默认 输出 文件 的 操作 ， 所 有 的 输入 输出 操作 都 针对 这 些 默认 文件 。 第 二 种 风 
格 使 用 显 式 的 文件 句柄 。 


当 使 用 隐 式 文件 句柄 时 ， 所 有 的 操作 都 由 表 io 提供 。 若 使 用 显 式 文件 句柄 ， io.open 会 
返回 一 个 文件 句柄 ， 且 所 有 的 操作 都 由 该 文件 句柄 的 方法 来 提供 。 


表 io 中 也 提供 了 三 个 和 C 中 含义 相同 的 预定 义 文件 句柄 : io.stdin ， io.stdout ， 以 
及 io.stderr 。 1/O 库 永远 不 会 关闭 这 些 文件 。 


除非 另 有 说 明 ， I/O 函数 在 出 错时 都 返回 nil 〈 第 二 个 返回 值 为 错误 消息 ， 第 三 个 返回 值 为 系 
统 相关 的 错误 码 ) 。 成 功 时 返回 与 nil 不 同 的 值 。 在 非 POSIX 系统 上 ， 根据 错误 码 取出 错 
误 消 息 的 过 程 可 能 并 非 线程 安全 的 ， 因为 这 使 用 了 C 的 全 局 变量 errno 。 


io.close ([file]) 
等 价 于 file:close() 。 不 给 出 file 时 将 关闭 默认 输出 文件 。 
io.flush () 


等 价 于 io.output():flush() 。 


io.input ([file]) 


用 文件 名 调用 它 时 ， (以 文本 模式 ) 来 打开 该 名 字 的 文件 ， 并 将 文件 句柄 设 为 默认 输入 文 
件 。 如 果 用 文件 句柄 去 调用 它 ， 就 简单 的 将 该 句柄 设 为 默认 输入 文件 。 如 果 调 用 时 不 传 参 
数 ， 它 返回 当前 的 默认 输入 文件 。 


在 出 错 的 情况 下 ， 画 数 抛 出 错误 而 不 是 返回 错误 码 。 


io.lines ([filename ..:.:]) 


以 读 模 式 打 开 指 定 的 文件 名 并 返回 一 个 迭代 郴 数 。 此 迭代 画 数 的 工作 方式 和 用 一 个 已 打开 的 
文件 去 调用 file:1lines(.….) 得 到 的 迭代 器 相同 。 当 迭 代 画 数 检测 到 文件 结束 ， 它 不 返回 值 
(让 循环 结束 ) 并 自动 关闭 文件 。 

调用 io.lines() (不 传 文件 名 ) 等 价 于 io.input():lines("*1") ; 即 ， 它 将 按 行 迭代 标准 
输入 文件 。 在 此 情况 下 ， 循 环 结束 后 它 不 会 关闭 文件 。 


在 出 错 的 情况 下 ， 画 数 抛 出 错误 而 不 是 返回 错误 码 。 


io.open (filename [，mode]) 


这 个 玉 数 用 字符 捉 mode 指定 的 模式 打开 一 个 文件 。 返回 新 的 文件 句柄 。 当 出 错时 ， 返 回 
nil 加 错误 消息 。 


mode 字符 串 可 以 是 下 列 任意 值 : 


。 "r ": 读 模式 〈 默 认 ) 

。"w": 写 模 式 ; 

。" a ": 追加 模式 ; 

。" r+ ": 更 新 模式 ， 所 有 之 前 的 数据 都 保留 ; 

。" w+ ": 更 新 模式 ， 所 有 之 前 的 数据 都 删除 ; 

。" a+ ": 追加 更 新 模式 ， 所 有 之 前 的 数据 都 保留 ， 只 人 允许 在 文件 尾部 做 写 入 。 


mode 字符 串 可 以 在 最 后 加 一 个 'b'， 这 会 在 某 些 系统 上 以 二 进 制 方式 打开 文件 。 
io.output ([file]) 


类 似 于 io.input 。 不 过 都 针对 默认 输出 文件 操作 。 


io.popen (prog [, model]) 
这 个 函数 和 系统 有 关 ， 不 是 所 有 的 平台 都 提供 。 


用 一 个 分 离 进 程 开 启程 序 prog ， 返回 的 文件 句柄 可 用 于 从 这 个 程序 中 读 取 数据 (如 果 
mode 为 "r" ， 这 是 默认 值 ) 或 是 向 这 个 程序 写 入 输入 ( 当 mode 为 "w” 时 ) 。 


io.read (:.:.:) 

等 价 于 io.input():read(.…) 。 

io.tmpfile () 

返回 一 个 临时 文件 的 句柄 。 这 个 文件 以 更 新 模式 打开 ， 在 程序 结束 时 会 自动 删除 。 


io.type (obj ) 


检查 obj 是 否 是 合法 的 文件 句柄 。 如 果 obj 它 是 一 个 打开 的 文件 句柄 ， 返 回 字 符 串 
"file" 。 如 果 obj 是 一 个 关闭 的 文件 句柄 ， 返 回 字符 串 "closed file" 。 如 果 obj 不 是 
文件 句柄 ， 返 回 nil 。 


io.write (.:…:) 


等 价 于 io.output():write(.'.) o 


file:close () 


关闭 file 。 注意 ， 文 件 在 句柄 被 垃圾 回收 时 会 自动 关闭 ， 但 是 多 久 以 后 发 生 ， 时 间 不 可 预 
期 的 。 


当 关 闭 用 io.popen 创建 出 来 的 文件 句柄 时 ， file:close 返回 o0s.execute 会 返回 的 一 样 的 
值 。 


file:flush () 
将 写 入 的 数据 保存 到 file 中 。 
file:lines (..:.) 


返回 一 个 迭代 器 函数 ， 每 次 调用 和 迭代 器 时 ， 都 从 文件 中 按 指 定格 式 读 数据 。 如 果 没 有 指定 格 
式 ， 使 用 默认 值 " 1"。 看 一 个 例子 


for c in file:lines(1) do _body_ end 


会 从 文件 当前 位 置 开 始 ， 中 不 断 读 出 字符 。 和 io.1lines 不 同 ， 这 个 事 数 在 循环 结束 后 不 会 
天 闭 文件 。 


在 出 错 的 情况 下 ， 画 数 抛 出 错误 而 不 是 返回 错误 码 。 
file:read (.:.:) 


读 文 件 file ， 指定 的 格式 决定 了 要 读 什 么 。 对 于 每 种 格式 ， 豆 数 返回 读 出 的 字符 对 应 的 字 
符 串 或 数字 。 若 不 能 以 该 格式 对 应 读 出 数据 则 返回 nil。 (对 于 最 后 这 种 情况 ， 画 数 不 会 读 
出 后 续 的 格式 。) 当 调 用 时 不 传 格式 ， 它 会 使 用 默认 格式 读 下 一 行 ( 见 下 面 描述 ) 。 


提供 的 格式 有 


。" n": 读 取 一 个 数字 ， 根 据 Lua 的 转换 文法 ， 可 能 返回 浮 点 数 或 整数 。 (数字 可 以 有 前 
置 或 后 置 的 空格 ， 以 及 符号 。) 只 要 能 构成 合法 的 数字 ， 这 个 格式 总 是 去 读 尽 量 长 的 
串 ; 如 果 读 出 来 的 前 级 无 法 构成 合法 的 数字 (比如 空 种 ，" ex" 或" 3.4e- ") ， 就 中 止 
画 数 运行 ， 返 回 nil。 

e。 "iu": 读 取 一 个 整数 ， 返 回 整数 值 。 

e。"a ": 从 当前 位 置 开 始 读 取 整 个 文件 。 如 果 已 在 文件 末尾 ， 返 回 空 串 。 

。 "1 ": 读 取 一 行 并 忽略 行 结束 标记 。 当 在 文件 末尾 时 ， 返 回 nil 这 是 默认 格式 。 

。"L": 读 取 一 行 并 保留 行 结 束 标记 (如果 有 的 话 ) ， 当 在 文件 末尾 时 ， 返 回 nil。 

。 number: 读 取 一 个 不 超过 这 个 数量 字 节 数 的 字符 串 。 当 在 文件 末尾 时 ， 返 回 nil。 如 果 
number 为 需 ， 它 什 么 也 不 读 ， 返 回 一 个 空 串 。 当 在 文件 末尾 时 ， 返 回 nil。 


格式 " 1 " 和 " L "只 能 用 于 文本 文件 。 


file:seek ([whence [, offset]]) 





设置 的 位 置 由 offset 和 whence 字符 串 








设置 及 获取 基于 文件 开头 处 计算 出 的 位 置 。 
whence 指定 的 基点 决定 。 基点 可 以 是 : 


@ " set 让 基点 为 0 (文件 开头 ) 

e。 "cur ": 基点 为 当前 位 置 了 ; 

e。" end ": 基点 为 文件 尾 ; 
当 seek 成 功 时 ， 返 回 最 终 从 文件 开头 计算 起 的 文件 的 位 置 。 
上 一 个 错误 描述 字符 串 。 


当 seek 失败 时 ， 返 回 nil 加 


因此 ， 调 用 file:seek() 可 以 返回 文件 


whence 的 默认 值 是 "cur" ， offset 默认 为 0。 
; 调用 


当前 位 置 ， 并 不 改变 它 ; 调用 file:seek("set") 将 位 置 设 为 文件 开头 (并 返回 0) 
file:seek("end") 将 位 置 设 到 文件 末尾 ， 并 返回 文件 大 小 。 


file:setvbuf (mode [, size]) 


设置 输出 文件 的 缓冲 模式 。 有 三 种 模式 : 
。" no ": 不 缓冲 ; 输出 操作 立刻 生效 。 
。 "full ": 完全 缓冲 ; 只 有 在 缓存 满 或 当 你 显 式 的 对 文件 调用 flush 
时 才 真 正 做 输出 操作 。 
。" line ": 行 缓冲 ; 输出 将 到 每 次 换行 前 ， 
何 输入 前 。 
对 于 后 两 种 情况 ， size 以 字 节 数 为 单位 指定 缓冲 区 大 小 。 


(参见 io.flush ) 


对 于 某 些 特殊 文件 (例如 终端 设备 ) 缓冲 到 任 
默认 会 有 一 个 恰当 的 大 小 。 


file:write (..:.) 
将 参数 的 值 逐 个 写 入 file 。 参数 必须 是 字符 串 或 数字 。 


成 功 时 ， 画 数 返 回 file 。 否则 返回 nil 加 错误 描述 字符 串 。 


6.9 -- 操作 系统 库 
这 个 库 都 通过 表 os 实现 。 


os.clock () 


返回 程序 使 用 的 按 秒 计 CPU 时 间 的 近似 值 。 


os.date ([format [, time]]) 


返回 一 个 包含 日 期 及 时 刻 的 字符 串 或 表 。 格式 化 方法 取决 于 所 给 字符 串 format 。 


如 果 提 供 了 time 参数 ， 格式 化 这 个 时 间 (这 个 值 的 含义 参见 os.time 贺 数 ) 。 否 
则 ， date 格式 化 当前 时 间 。 


如 果 format 以 ' ! ' 打 头 ， 日 期 以 协调 世界 时 格式 化 。 在 这 个 可 选 字符 项 之 后 ， 如 果 
format 为 字符 串 " *t "， date 返回 有 后 续 域 的 表 : year 【〔 四 位 数字 ) ， month (1-- 
12) ， day (1-31) , hour (0-23) ， man (0-59) ， Sec (0-61) ? wday ( 星 
期 几 ， 星 期 天 为 1) ， yday (当年 的 第 几 天 ) ， 以 及 isdst 《夏令 时 标记 ， 一 个 布尔 
量 ) 。 对 于 最 后 一 个 域 ， 如 果 该 信息 不 提供 的 话 就 不 存在 。 


如 果 format 并 非 "Be, date 以 字符 串 形式 返回 ， 格式 化 方法 遵循 ISOC 轴 数 
strftime 的 规则 。 


如 果 不 传 参数 调用 ， date 返回 一 个 合理 的 日 期 时 间 串 ， 格式 取决 于 宿主 程序 以 及 当前 的 区 
域 设 置 ( 即 ， os.date() 等 价 于 os.date("%c") ) 。 


在 非 POSIX 系统 上 ， 由 于 这 个 男 数 依 赖 C 本 数 gmtime 和 localtime ， 它 可 能 并 非 线程 安 
全 的 。 
os.difftime (t2, t1) 


返回 以 秒 计 算 的 时 刻 tt 到 t2 的 差 值 。 (这 里 的 时 刻 是 由 os.time 返回 的 值 ) 。 在 
POSIX，Windows， 和 其 它 一 些 系 统 中 ， 这 个 值 就 等 于 t2 -ti 。 


os.execute ([command ] ) 


这 个 本 数 等 价 于 ISO C 画 数 system 。 它 调用 系统 解释 器 执行 command 。 如 果 命 合成 功 运 
行 完 毕 ， 第 一 个 返回 值 就 是 true， 否则 是 nil otherwise。 在 第 一 个 返回 值 之 后 ， 郴 数 返回 一 
个 字符 串 加 一 个 数字 。 如 下 : 


。" exit ": 命 人 正常 结束 ; 接 下 来 的 数字 是 命 全 的 退出 状态 码 。 
。" signal ": 命令 被 信号 打 断 ; 接 下 来 的 数字 是 打 断 该 命 全 的 信号 。 


如 果 不 带 参数 调用 ， os.execute 在 系统 解释 器 存在 的 时 候 返 回 真 。 


os.exit ([code [，close]]) 


调用 ISO C 男 数 exit 终止 宿主 程序 。 如 果 code 为 true， 返回 的 状态 码 是 
EXIT_SUCCESS ; 如 果 code 为 false， 返回 的 状态 码 是 EXIT_FAILURE ; 如 果 code 是 一 个 
数字 ， 返回 的 状态 码 就 是 这 个 数字 。 code 的 默认 值 为 true。 


如 果 第 二 个 可 选 参数 close 为 真 ， 在 退出 前 关闭 Lua 状态 机 。 


os.getenv (varname ) 


返回 进程 环境 变量 varname 的 值 ， 如 果 该 变量 未 定义 ， 返 回 nil 。 


os.remove (filename ) 


删除 指定 名 字 的 文件 〈 在 POSIX 系统 上 可 以 是 一 个 空 目录 ) 如 果 函 数 失败 ， 返 回 nil 加 一 个 
鞋 误 描 述 串 及 出 错 码 。 


os.rename (oldname, newname) 


将 名 字 为 oldname 的 文件 或 目录 更 名 为 newname 。 如 果 画 数 失 败 ， 返 回 nil 加 一 个 错误 描述 
串 及 出 错 码 。 


os.setlocale (locale [, category]) 


设置 程序 的 当前 区 域 。 1locale 是 一 个 区 域 设置 的 系统 相关 字符 上 串 ; ”category 是 一 个 描述 
有 改变 哪个 分 类 的 可 选 字符 串 : "all" ， "collate" ， "ctype" ， "monetary"， 

"numeric" ， 或 Elimesa ， 默认 的 分 类 为 wa eo 此 画 数 返回 新 区 域 的 名 字 。 如 果 请 求 未 
被 获准 ， 返 回 nil 。 


当 1locale 是 一 个 空 串 ， 当前 区 域 被 设置 为 一 个 在 实现 中 定义 好 的 本 地 区 域 。 当 1locale 为 
字符 串 " c "， 当前 区 域 被 设置 为 标准 C 区 域 。 


当 第 一 个 参数 为 nil 时 ， 此 画 数 仅 返 回 当前 区 域 指定 分 类 的 名 字 。 
由 于 这 个 画 数 依赖 © 轴 数 setlocale,， 它 可 能 并 非 线程 安全 的 。 


os.time ([table]) 


当 不 传 参数 时 ， 返 回 当 前 时 刻 。 如 果 传 入 一 张 表 ， 就 返回 由 这 张 表 表示 的 时 刻 。 这 张 表 必 须 
包含 域 year ， month ， 及 day ; 可 以 包含 有 hour (默认 为 12 ) ， min 【默认 为 
0) ， sec (默认 为 0) ， 以 及 isdst (默认 为 nil) 。 关于 这 些 域 的 详细 描述 ， 参 见 
DOswduatbce 画 数 。 


返回 值 是 一 个 含义 由 你 的 系统 决定 的 数字 。 在 POSIX，Windows， 和 其 它 一 些 系 统 中 ， 这 
个 数字 统计 了 从 指定 时 间 ("epoch") 开始 经 历 的 秒 数 。 对 于 另外 的 系统 ， 其 含义 未 定义 ， 
你 只 能 把 time 的 返回 数字 用 于 os.date 和 os.difftime 的 参数 。 


os.tmpname () 


返回 一 个 可 用 于 临时 文件 的 文件 名 字符 串 。 这 个 文件 在 使 用 前 必须 显 式 打 开 ， 不 再 使 用 时 需 
要 显 式 删除 。 


在 POSIX 系统 上 ， 这 个 函数 会 以 此 文件 名 创建 一 个 文件 以 回避 安全 风险 。 (别人 可 能 未 经 
允许 在 获取 到 这 个 文件 名 到 创建 该 文件 之 间 的 时 刻 创建 此 文件 。) 你 依旧 需要 在 使 用 它 的 时 
候 先 打开 ， 并 最 后 删除 (即使 你 没 使 用 到 ) 。 


只 有 有 可 能 ， 你 更 应 该 使 用 io.tmpfile ， 因为 该 文件 可 以 在 程序 结束 时 自动 删除 。 


6.10 -- 调试 库 


这 个 库 提 供 了 Lua 程序 调试 接口 〈$4.9) 的 功能 。 其 中 一 些 函 数 违反 了 Lua 代码 的 基本 假定 
(例如 ， 不 会 从 画 数 之 外 访问 男 数 的 局 部 变量 ; 用 户 数据 的 元 表 不 会 被 Lua 代码 修改 ; Lua 
程序 不 会 崩溃 ) ， 因此 它们 有 可 能 危害 到 其 它 代码 的 安全 性 。 此 外 ， 库 里 的 一 些 画 数 可 能 运 
行 的 很 慢 。 


个 库 里 的 所 有 男 数 都 提供 在 表 debug 内 。 所 有 操作 线程 的 函数 ， 可 选 的 第 一 个 参数 都 是 
默认 值 永远 是 当前 线程 。 


debug.debug () 


进入 一 个 用 户 交 互 模式 ， 运 行 用 户 输入 的 每 个 字符 串 。 使 用 简单 的 命令 以 及 其 它 调 试 设置 ， 
用 户 可 以 检阅 全 局 变量 和 局 部 变量 ， 改变 变量 的 值 ， 计 算 一 些 表达 式 ， 等 等 。 输入 一 行 仅 包 
含 cont 的 字符 串 将 结束 这 个 贺 数 ， 这 样 调用 者 就 可 以 继续 向 下 运行 。 


注意 ， debug.debug 输入 的 命令 在 文法 上 并 没有 内 财 到 任何 画 数 中 ， 因此 不 能 直接 去 访问 局 
部 变量 。 


debug.gethook ([thread] ) 


回 三 个 表示 线程 钩子 设置 的 值 : 当前 钩子 函数 ， 当 前 钩子 掩 码 ， 当 前 钩子 计数 
debug.sethook 设置 的 那些 ) o 


debug.getinfo ([thread,] f [, what]) 


返回 关于 一 个 玉 数 信息 的 表 。 你 可 以 直接 提供 该 酚 数 ， 也 可 以 用 一 个 数字 f 表示 该 画 数 。 

数字 f 人 定 线 程 的 调用 栈 对 应 层次 上 的 函数 : 0 层 表 示 当 前 画 数 ( getinfo 自 

身 ) ; 1 层 表 示 调 用 getinfo 的 函数 (除非 是 尾 调 用 ， 这 种 情况 不 计 入 栈 ) ; 等 等 。 如 果 
es 大 的 数字 ， getinfo 返回 nil。 


只 有 字符 串 what 0 些 项 ， 返 返回 的 表 可 以 包含 Jua getinfo 能 返回 的 所 有 
项 。 what 默认 是 返回 提供 的 除 合 法 行 号 表 外 的 所 有 信息 。 对 于 选项 ' f'， 会 在 可 能 的 情况 
下 ， 增 加 func 域 保 存 函 数 自身 。 ty L'， 会 在 可 能 的 情况 下 ， 增 加 activelines 
域 保存 合法 行 号 


例 如 ,表达 式 debug.getinfo(1,"n") 返回 带 有 当前 函 打数 名 字 信 息 的 表 (如 果 找 的 至 到 名 字 的 
话 ) y 表达 式 debug.getinfo(print) 返回 关于 print 本 数 的 包含 有 所 有 让 能 提供 信息 的 表 。 


debug.getlocal ([thread,] f, local) 


此 函数 返回 在 栈 的 f 层 处 豆 数 的 索引 为 local 的 局 部 变量 的 名 字 和 值 。 这 个 加 数 不 仅 用 
于 访问 显 式 定义 的 局 部 变量 ， 也 包括 形 参 、 临 时 变量 等 。 


第 一 个 形 参 或 是 定义 的 第 一 个 局 部 变量 的 索引 为 1 ， 然后 遵循 在 代码 中 定义 次 序 ， 以 次 类 
推 。 其 中 只 计算 汞 数 当 前 作用 域 的 活动 变量 。 负 索 引 指 可 变 参数 ; -1 指 第 一 个 可 变 参 数 。 
如 果 该 索引 处 没有 变量 ， 男 数 返 回 nil。 若 指定 的 层次 越界 ， 抛 出 错误 。 【你 可 以 调用 
debug.getinfo 来 检查 层次 是 否 合法 。 ) 


以 " ( ' 〈 开 括号 ) 打头 的 变量 名 表示 没有 名 字 的 变量 〈 比 如 是 循环 控制 用 到 的 控制 变量 ， 或 
是 去 除了 调试 信息 的 代码 块 ) 。 


参数 f 也 可 以 是 一 个 画 打数 。 这 种 情况 下 ， getlocal 仅 返 回 函 数 形 参 的 名 字 。 
debug.getmetatable (value) 


返回 给 定 value 的 元 表 。 若 其 没有 元 表 则 返回 nil 。 


debug.getregistry () 


回 注册 表 (参见 $4.5) 。 


debug.getupvalue (f, up) 
此 冰 数 返回 函数 f 的 第 up 个 上 值 的 名 字 和 值 。 如 果 该 本 数 没有 那个 上 值 ， 返 回 nil 。 
以 ' (' ( 开 括 号) 打头 的 变量 名 表示 没有 名 字 的 变量 〈 去 除了 调试 信息 的 代码 块 ) 。 


debug.getuservalue (u) 


返回 关联 在 u 上 的 Lua 值 。 如 果 u 并 非 用 户 数 据 ， 返 回 nil。 


debug.sethook ([thread,] hook, mask [, count]) 


一 个 函数 作为 钧 子 函 数 设 入 。 字符 串 mask 以 及 数字 count 决定 了 钧 子 将 在 何 时 调用 。 
ee A 每 个 字符 有 其 含义 : 


。'c 每 当 Lua 调用 一 个 画 数 时 ， 调 用 钧 子 ; 
。'r 每 当 Lua 从 一 个 画 数 内 返回 时 ， 调 用 钩子 ; 
e。 "1 每 当 Lua 进入 新 的 一 行 时 ， 调 用 钩子。 


此 外 ， 传 入 一 个 不 为 需 的 count ， 钧 子 将 在 每 运行 count 条 指令 时 调用 。 
如 果 不 传 人 参数 ， debug .sethook 关闭 钩子 。 


当 钧 子 被 调用 时 ， 第 一 个 参数 是 触发 这 次 调用 的 事件 : "call" (或 "tail call" ) ， 
"return" ， "Line" ， "count" 。 对 于 行事 件 ， 钧 子 的 第 二 个 参数 是 新 的 行 号 。 在 钩子 
内 ， 你 可 以 调用 getinfo ， 指 定 第 2 层 ， 来 获得 正在 运行 的 函数 的 详细 信息 (0 层 指 
getinfo 本 数 ， 1 层 指 钓 子 范 数 ) o 


debug.setlocal ([thread,] level, local, value) 


这 个 本 数 将 value 赋 给 栈 上 第 level 层 辑 数 的 第 local 个 局 部 变量 。 如 果 没 有 那个 变 
量 ， 画 数 返 回 nil 。 如 果 1level 越界 ， 抛 出 一 个 错误 。 (你 可 以 调用 debug.getinfo 来 检 
查 层次 是 否 合法 。) 否则 ， 它 返回 局 部 变量 的 名 字 。 


关于 变量 索引 和 名 字 ， 参 见 debug.getlocal 。 
debug.setmetatable (value, table) 


将 value 的 元 表 设 为 table (可 以 是 nil) 。 返回 value 。 


debug.setupvalue (f, up, value) 


这 人 TO value 设 为 函数 f 的 第 up 个 上 值 。 如 果 画 数 没 有 那个 上 值 ， 返 回 nil 否 
则 ， 返 回 该 上 值 的 名 字 。 


debug.setuservalue (udata, value) 


将 value 设 为 udata 的 关联 值 。 udata 必须 是 一 个 完全 用 户 数 据 。 


返回 udata 。 


debug.traceback ([thread,] [message [, levell]]) 


如 果 message 有 ， 且 不 是 字符 串 或 nil， 函数 不 做 任何 处 理 直 接 返回 message 。 否则 ， 它 返 
回调 用 栈 的 栈 回溯 信息 。 字符 串 可 选项 message 被 添加 在 栈 回溯 信息 的 开头 。 数字 可 选项 
level 指明 从 栈 的 哪 一 层 开 始 回溯 (默认 为 1 ， 即 调用 traceback 的 那里 ) 。 
debug.upvalueid (f, n) 

返回 指定 函数 第 n 个 上 值 的 唯一 标识 符 ( 一 个 轻 量 用 户 数据 ) 。 


个 唯一 标识 符 可 以 让 程序 检查 两 个 不 同 的 闭 包 是 否 共享 了 上 值 。 若 Lua 闭 包 之 间 共 享 的 是 
= 个 上 值 ( 即 指向 一 个 外 部 局 部 变量 ) ， 会 返回 相同 的 标识 符 。 


debug.upvaluejoin (f1, ni, f2, n2) 


让 Lua 闭 包 fi 的 第 ni 个 上 值 引用 Lua 闭 包 f2 的 第 nz 个 上 值 。 


7 -- 独立 版 Lua 


虽然 Lua 被 设计 成 一 门 扩展 式 语言 ， 用 于 钦 入 一 个 宿主 程序 。 但 经 常 也 会 被 当成 独立 语言 使 
用 。 独立 版 的 Lua 语言 解释 器 随 标 准 包 发 布 ， 就 叫 lua 。 独立 版 解释 器 保留 了 所 有 的 标准 
库 及 调试 库 。 其 命令 行 用 法 为 : 


JuUa [options] [script [args]] 


选项 有 : 


。 -e _stat_: 执行 一 段 字符 串 stat ; 

。 -1 _mod_ : “请 求 模块 "mmoal ; 

。 -i :在 运行 完 脚本 后 进入 交互 模式 ; 

。 -v : 打印 版 本 信息 ; 

e。 -E :忽略 环境 变量 ; 

e。 -- :中 止 对 后 面 选 项 的 处 理 ; 

。 - :把 stdin 当 作 一 个 文件 运行 ， 并 中 止 对 后 面 选项 的 处 理 。 


在 处 理 完 选 项 后 ， lua 运行 指定 的 脚本 。 如 果 不 带 参数 调用 ， 在 标准 输入 〈 stdin ) 是 终 
端 时 ， lua 的 行为 和 lua -v -i 相同 。 否则 相当 于 lua - o 


如 果 调 用 时 不 带 选项 -E ， 解释 器 会 在 运行 任何 参数 前 ， 检 查 环 境 变 量 LuA_INIT 5 3 (或 
在 版 本 名 未 定义 时 ， 检 查 LUA_INIT ) 。 如 果 该 变量 内 存 格式 为 @ filename ， lua 执行 
该 文件 。 否则 ， lua 执行 该 字符 串 。 


如 果 调 用 时 有 选项 -E ， 除 了 忽略 LuA_INIT 外 ， Lua 还 忽略 LUA_PATH 与 LUA_cPATH 的 
值 。 将 package.path 和 package.cpath 的 值 设 为 定义 在 luaconf.h 中 的 默认 路 径 。 


除 -i 与 -E 外 所 有 的 选项 都 按 次 序 处 理 。 例如 ， 这 桩 调用 

$ lua -e'a=1' -e 'print(a)' script.lua 
将 先 把 a 设 为 {1， 然 后 打印 a 的 值 ， 最 后 运行 文件 script.1ua 并 不 带 参数 。 (这 里 的 
$ 是 命令 行 提示 。 你 的 命令 行 提 示 可 能 不 一 样 。) 


在 运行 任何 代码 前 ， lua 会 将 所 有 命令 行 传人 的 参数 放 到 一 张 全 局 表 arg 中 。 脚本 的 名 字 
放 在 索引 0 的 地 方 ， 脚 本 名 后 紧 跟 的 第 一 个 参数 在 索引 1 处 ， 依 次 类 推 。 在 脚本 名 前 面 的 任 
何 参数 〈 即 解释 器 的 名 字 以 及 各 选项 ) 放 在 负 索 引 处 。 例如 ， 调 用 


$ lua -la b.lua t1 t2 


这 张 表 是 这 样 的 : 


aro = a 
[0 = "Be lua., 
[1] -= tT [2] = nt2n } 


如 果 调 用 中 没 提供 脚本 名 ， 解释 器 的 名 字 就 放 在 索引 0 处 ， 后 面 接着 其 它 人 参数。 例如 ， 调 用 


$ lua -e "print(arg[1])" 


将 打印 出 "”-e" 。 如 果 提 供 了 脚本 名 ， 就 以 arg[1] ,…，arg[#arg] 为 参数 调用 脚本 。 (和 
Lua 所 有 的 代码 块 一 样 ， 脚本 被 编译 成 一 个 可 变 参 数 画 数 。) 


在 交互 模式 下 ， Lua 不 断 的 显示 提示 符 ， 并 等 待 下 一 行 输入 。 一 旦 读 到 一 行 ， 首先 试 着 把 这 
行 解释 为 一 个 表达 式 。 如 果 成 功 解释 ， 就 打印 表达 式 的 值 。 否则 ， 将 这 行 解释 为 语句 。 如 果 
你 写 了 一 行 未 完成 的 语句 ， 解释 器 会 用 一 个 不 同 的 提示 符 来 等 待 你 写 完 。 


当 脚 本 中 出 现 了 未 保护 的 错误 ， 解释 器 向 标准 错误 流 报告 错误 。 如 果 错 误 对 象 并 非 一 个 字符 
串 ， 但 是 却 有 元 方法 _tostring 的 话 ， 解释 器 会 调用 这 个 元 方法 生成 最 终 的 消息 。 否则 ， 
解释 器 将 错误 对 象 转换 为 一 个 字符 串 ， 并 把 栈 回溯 信息 加 在 前 面 。 


如 果 正 常 结束 运行 ， 解释 器 会 关闭 主 Lua 状态 机 (参见 lua_close ) 。 脚本 可 以 通过 调用 
os.exit 来 结束 ， 以 回避 这 个 步骤 。 


为 了 让 Lua 可 以 用 于 Unix 系统 的 脚本 解释 器 。 独立 版 解释 器 会 忽略 代码 块 的 以 # 打头 的 
第 一 行 。 因此 ，Lua 脚本 可 以 通过 chmod +x 以 及 # 形式 变 成 一 个 可 执行 文件 。 类 似 这 样 


#1!/UusSr/local/bin/lua 


(当然 ，Lua 解释 器 的 位 置 对 于 你 的 机 器 来 说 可 能 不 一 样 。 如 果 lua 在 你 的 PATH 中 ， 写 
成 


#!/usSr/bin/env lua 


8 -与 之 前 版 本 不 兼容 的 地 方 


这 里 我 们 列 出 了 把 程序 从 Lua 5.2 迁移 到 Lua 5.3 会 碰 到 的 不 兼容 的 地 方 。 你 可 以 在 编译 
Lua 时 定义 一 些 恰当 的 选项 (参见 文件 luaconf.h ) ， 来 回避 一 些 不 兼容 性 。 然而 ， 这 些 兼 
容 选 项 以 后 会 移 除 。 


Lua 的 版 本 更 替 总 是 会 修改 一 些 C API 并 涉及 源 代 码 的 改变 。 例如 一 些 常量 的 数字 值 ， 用 宏 
来 实现 一 些 函 数 。 因此 ， 你 不 能 假设 在 不 同 的 Lua 版 本 间 可 以 做 到 二 进 制 兼容 。 当 你 使 用 新 
版 时 ， 一 定 要 将 使 用 了 Lua API 的 客户 程序 重新 编译 。 


同样 ，Lua 版 本 更 蔡 还 会 改变 预 编译 代码 块 的 内 部 呈现 方式 ; 在 不 同 的 Lua 版 本 间 ， 预 编译 
代码 块 不 兼容 。 


官方 发 布 版 的 标准 路 径 也 可 能 随 版 本 变化 。 


8.1 -- 语言 的 变更 


。 Lua 5.2 到 Lua 5.3 最 大 的 变化 是 引入 了 数字 的 整数 子 类 型 。 虽然 这 个 变化 不 会 影响 “一 
般 ” 计 算 ， 但 一 些 计 算 (主要 是 涉及 浴 出 的 ) 会 得 到 不 同 的 结果 。 


你 可 以 通过 把 数字 都 强制 转换 为 浮 点 数 来 消除 差异 (在 Lua 5.2 中 ， 所 有 的 数字 都 是 浮 
点 数 ) 。 比如 你 可 以 将 所 有 的 常量 都 以 .8 结尾 ， 或 是 使 用 x = x + 9.9 来 转换 一 个 
变量 。 〈 这 条 建议 仅 用 于 偶尔 快速 解决 一 些 不 兼容 问题 ; 这 不 是 一 条 好 的 编程 准则 。 好 
好 写 程 序 的 话 ， 你 应 该 在 需要 使 用 浮 点 数 的 地 方 用 浮 点 数 ， 需要 整数 的 地 方 用 整数 。) 


。 把 浮 点 数 转 为 字符 串 的 地 方 ， 现 在 都 对 等 于 整数 的 浮 点 数 加 了 .6 后 级 。 (例如 ， 浮 点 
数 2.0 会 被 打印 成 2.6 ， 而 不 是 2 。) 如果 你 需要 定制 数字 的 格式 ， 就 必须 显 式 的 格 
式 化 它们 。 

(准确 说 这 个 不 是 兼容 性 问题 ， 因为 Lua 并 没有 规定 数字 如 何 格式 化 成 字符 串 ， 但 一 些 
程序 假定 遵循 某 种 特别 的 格式 。) 


。 分 代 垃 圾 收集 器 没有 了 。 【〔 它 是 Lua 5.2 中 的 一 个 试验 性 特性 。) 


8.2 一 库 的 变更 


e。 bit32 库 废 奔 了 。 使 用 一 个 外 部 兼容 库 很 容易 ， 不 过 最 好 直接 用 对 应 的 位 操作 符 来 蔡 
换 它 。 (注意 bit32 只 能 针对 32 位 整数 运算 ， 而 标准 Lua 中 的 位 操作 可 以 用 于 64 位 
整数 。) 

。 表 处 理 库 现在 在 读 写 其 中 的 元 素 时 会 考虑 元 方法 。 

e。 ipairs 这 个 迭代 器 也 会 考虑 元 方法 ， 而 _ ipairs 元 方法 被 废 奔 了 。 


LO nead 的 选项 名 不 再 用 “打头 。 但 出 于 兼容 性 考虑 ， Lua 会 继续 忽略 掉 这 个 字符 。 
数学 库 中 的 这 些 本 数 废弃 了 * atan2 ， cosh ， sinh ， tanh ， pow ， frexp ， 以 
及 ldexp 。 你 可 以 用 x^y 替换 

math.pow(x,y) ; 你 可 以 用 math.atan 蔡 换 math.atan2 ， 前 者 现在 可 以 接收 一 或 两 个 参数 ; 你 可 以 用 
X 2.0^exp 替换 math.Idexp(X,eXp) 。 若 用 到 其 它 操作 ， 你 可 以 写 一 个 扩展 库 ， 或 在 Lua 中 实现 它们 。 

” require 在 搜索 C 加 载 器 时 处 理 版 本 号 的 方式 有 所 变化 。 现在 ， 版 本 号 应 该 跟 在 模块 
名 后 (其 它 大 多 数 工 具 都 是 这 样 干 的 ) 。 出 于 兼容 性 考虑 ， 如 果 使 用 新 格式 找 不 到 加 载 
器 的 话 ， 搜 索 器 依然 会 党 试 旧 格式 。 (Lua 5.2 已 经 是 这 样 处 理 了 ， 但 是 并 没有 写 在 文档 
里 。)， 


8.3 -- API 的 变更 


延续 函数 现在 接收 原来 用 lua_getctx 获取 的 参数 ， 所 以 lua_getctx 就 去 掉 了 。 按 需 
要 改写 你 的 代码 。 

男 数 lua_dump 有 了 一 个 额外 的 参数 strip 。 如 果 想 和 之 前 的 行为 一 致 ， 这 个 值 传 0 。 
用 于 传 入 传 出 无 符号 整数 的 函数 ( Jua_pushunsigned， lua_tounsigned ， 

lJua_ tounsignedx ， Jual_checkunsigned ， lualL_optunsigned ) 都 废弃 了 。 直接 从 有 符 
号 版 做 类 型 转换 。 

处 理 输入 非 默认 整数 类 型 的 宏 ( luaL_checkint ， 1luaL_optint ， 1luaL_checklong ， 
luaL_optlong ) 废弃 掉 了 。 直接 使 用 lua_integer 加 一 个 类 型 转换 就 可 以 替代 (或 是 
只 要 有 可 能 ， 就 在 你 的 代码 中 使 用 lua Integer ) 。 


9 -Lua 的 完整 语法 


这 是 一 份 采用 扩展 BNF 描述 的 Lua 完整 语法 。 在 扩展 BNF 中 ， {A} 表示 0 或 多 个 人 A， [A] 
表示 一 个 可 选 的 A。 (操作 符 优先 级 ， 参 见 $3.4.8 ; 对 于 最 终 符 号 ， 名 字 ， 数 字 ， 字 符 串 字 
面 量 的 解释 ， 参 见 §3.1。) 


chunk ::= block 
block ::= {stat} [retstat] 


stat ::= ent 
Varnlrst =“ explistl 
functioncall | 
label | 
**break** | 
**goto** Name | 
**do** block **end** | 
**while** exp **do** block **end** | 
**repeat** block **until** exp | 
**1f** exp **then** block {**elseif** exp **then** block} [**else** block] **end 
ye ee Name 4 大 大 一 大 大 了 exp exp | exp] OO** block *QNO** | 
**for** namelist **IN* "explist **do** "block **end**® | 
**function** funcname funcbody | 
**]ocal** **function** Name funcbody | 
**]Jocal** namelist [‘**=**’ explist] 


retstat := **return** [explist] | ** "| 

Dele = Naame 

funcname ::= Name {**.**’ Name} [‘**:**’ Name] 

varlist ::= Var {’**,**’ Var 

Var ::= Name | prefixexp “**[**’ exp “**]**’ | prefixexp “**.**" Name 

namelist ::= Name {**,**’ Name} 

explist ::= "exp {** +* exp} 

exp 1:= **nil** "| **false** | **true** | Numeral | LiteralString xs funct 


prefixexp | tableconstructor | exp binop exp | unop exp 


prefixexp ::= Var | functioncall] | ‘**(**’ exp ‘**)**" 

functioncall ::= prefixexp args | prefixexp ‘**:**’ Name args 

args ::= ‘“**(**’ [explist] ‘**)**’ | tableconstructor | LiteralString 

functiondef ::= **function** funcbody 

funcbody ::= ‘**(**’ [parlist] ‘**)**’ block **end** 

pornste.s:= mame lrsen le S00 人 交 人 

tableconstructor :三 是 “ss [ifrieLldlist ln “7 

fieldlist ::= field {fieldsep field} [fieldsep] 

field := **[** exp **]**’ **=**" exp | Name “**=**", exp | exp 

tnelodsepe := 0 

binop 一 ， 4 类 炎 十 火灾 了 | J | 下 | lst | A | xXKxAKKT | dy | 
Wd od | 4 | | | i | i | | 
71 大 大王 炎炎 7 | 和 | 4 | i bd | 4 大 大 一 一 大 类 / | 74 大 大 一 一 大 类/ | 


wwAand** | OT 


unop 一 和 | **nOt** | 四 | i 








Lua 5.3 术语 中 瑞 对 照 


译 者 在 翻译 时 ， 使 用 了 一 些 尚 未 统一 的 中 文 术语 译 词 ， 统 一 罗列 如 下 : 


元 表 metatable 

元 方法 metamethod 
弱 表 weak table 

协 程 coroutine 

闭 包 closure 

注册 表 registry 

让 出 yield 

表 table 

用 户 数据 userdata 

延续 点 continuation 
宿主 host 

一 等 公民 first-class 
语法 糖 syntactic sugar 
序列 sequence 

异 构 heterogeneous 
终结 器 finalizer 

暂时 表 ephemeron table 
符 记 token 

字面 串 literal string 
代码 块 chunk 

标签 label 

实例 化 instantiated 


上 值 upvalue 


关于 Lua 
Lua 是 一 门 强大 、 快 速 、 轻 量 的 伐 入 式 脚本 语言 。 它 由 巴西 里 约 热 内 卢 Pontifical Catholic 大 
学 的 PUC-Rio 团队 开发 。 Lua 是 一 个 自由 软件 ， 广泛 应 用 于 世界 上 无 数 产品 和 项 目 。 


Lua 的 官方 网 站 上 提供 了 关于 Lua 的 完整 信息 ， 包括 综合 概要 和 最 新 的 文档 ， 需要 注意 
的 是 参考 手册 可 能 和 这 里 的 版 本 有 所 不 同 。 


安装 Lua 


Lua 以 源 代码 的 形式 发 布 ， 使 用 之 前 ， 你 需要 构建 它 。 构建 Lua 非常 简单 ， 因 为 Lua 是 用 

纯粹 的 ANSI C 实现 的 ， 在 所 有 具 各 ANSI C 编译 器 的 平台 都 可 以 直接 编译 。 同时 ，Lua 也 

可 以 直接 以 C++ 形式 编译 。 下 面 介 绍 了 类 Unix 平台 上 的 构建 流程 ， 另 有 其 它 系 统 构 建 介绍 
与 配置 选项 以 作 参 考 。 


如 果 你 没有 时 间或 兴趣 自己 编译 Lua， 可 以 从 LuaBinaries 获取 编译 后 的 二 进 制 文件 或 者 从 
LuaDist 这 里 获取 Lua 的 多 平台 发 布 版 ( 自 带 电池 ) 。 


构建 Lua 
在 大 多 数 类 Unix 平台 上 ， 输 入 "make " 加 上 合适 的 平台 名 即 可 。 步 骤 如 下 : 


1. 打开 一 个 控制 台 窗 口 ， 切 换 到 lua-5.3.6 目录 。 目录 下 的 Makefile 文件 内 包含 了 构建 
与 安装 流程 。 
2. 运行 " make" 并 查看 你 的 平台 是 否 列 在 其 中 。 当前 支持 的 平台 有 : 


aix bsd c89 freebsd generic linux macosx mingw posix solaris 
如 果 你 的 平台 在 其 中 ， 运 行 " make xxx" 即 可 ，xxx 代表 你 的 平台 
如 果 你 的 平台 不 在 其 中 ， 先 党 试 最 相近 的 平台 ， 再 按 posix generic c89 顺序 依次 党 试 。 


3.， 编译 过 程 很 短 ， 最 终 在 src 目录 下 生成 三 个 文件 : lua (解释 器 ), luac (编译 器 ) 和 
liblua.a (静态 库 ) 。 


4. 构建 完成 后 ， 可 以 运行 " make test" 来 检查 是 否 成 功 。 它 会 运行 解释 器 并 打印 版 本 号 。 


如 果 你 是 Linux 系统 并 出 现 了 编译 错误 ， 请 确认 你 是 否 安装 了 readline (也 可 能 叫 
libreadline-dev 或 者 readline- devel ) 开发 包 。 之 后 ， 如 果 还 有 链接 错 错误 ， 党 试 


make linux MYLIBS=-ltermcap "”。 


安装 Lua 

一 旦 你 构建 完毕 ， 可 能 希望 把 Lua 安装 到 系统 默认 位 置 ， 那么 执行 " make install " 即 可 。 
系统 默认 位 置 以 及 如 何 安装 都 定义 在 Makefile 中 。 这 个 过 程 可 能 需要 有 相关 的 权限 。 
运行 " make xxx install " 可 以 构建 和 安装 一 步 到 位 ，xxx 指 你 的 平台 名 。 


如 果 你 想 把 Lua 安装 在 本 地 ， 运 行 " make local "。 会 创建 一 个 install 目录 ， 内 有 
bin ，include ，1lib ，man ，share , 子 目录 ， ER 如 果 你 想 安装 到 
本 地 其 它 目 录 ， 运行 " make install INSTALL_TOP=xxx "，XxXx 指 你 选择 的 目录 。 由 于 安装 过 程 


中 会 切换 到 src 以 及 doc 目录 进行 ， 所 以 当 INSTALL_TOP 不 是 绝对 路 径 时 务必 小 心 。 


bin: 

lua luac 

include: 

lauxlib.h lua.h Jua.hpp luaconf.h lualib.h 
lib: 

liblua.a 

man/mani1: 


lua.1 luac.1 


这 些 是 开发 时 需要 的 目录 。 如 果 你 仅仅 想 运 行 一 些 Lua 程序 ， 那么 只 需要 bin 和 man 下 
的 文件 。 include 和 1lib 下 的 文件 用 于 将 Lua 衣 入 C 或 C++ 程序 。 


定制 
有 三 类 定制 ， 可 以 通过 编辑 文件 完成 : 


。 怎样 安装 Lua 以 及 安装 到 哪里 一 编辑 Makefile 。 
e。 怎样 构建 Lua 一 编辑 src/Makefile 。 
。 Lua 特性 一 编辑 src/luaconf.h 。 


其 实 你 不 必 编辑 Makefile 文件 ，make 的 时 候 在 命令 行 指 定 相关 变量 即 可 。 当然 ， 编 辑 保存 
Makefile 可 以 给 定制 留 个 记录 。 


另 一 方面 ， 如 果 你 需要 定制 一 些 Lua 特性 ， 那 就 需要 在 构建 安装 Lua 前 编辑 src/luaconf.h 
。 编辑 过 的 文件 必须 确保 一 致 性 ， 也 就 是 只 安装 在 一 个 地 方 ， 让 所 有 你 编译 出 来 的 用 到 Lua 
的 程序 都 使 用 这 唯一 的 这 一 份 。 专家 可 以 通过 编辑 Lua 源 代码 来 定制 更 多 的 东西 。 


在 其 它 系 统 上 构建 Lua 


如 果 你 不 使 用 常规 的 Unix 工具 ， 那 么 构建 Lua 的 流程 就 取决 于 你 使 用 的 编译 器 。 你 需要 创 
建 若 干 工程 来 构建 库 ， 解 释 器 以 及 编译 器 等 。 请 把 下 列 源 文件 加 入 相关 工程 : 


库 : 


e lapi.c 

e |code.c 

e Ictype.c 
e ldebug.c 
e |do.c 

e ldump.c 


e lfunc.c 

e lgc.c 

e llex.c 

。 Imem.c 
e lobject.c 
®。 lopcodes.c 
e lparser.c 
e lstate.c 
e lstring.c 
e ltable.c 
e ltm.c 

®。 lundump.c 
e lvm.c 

e lzio.c 

e lauxlib.c 
e lbaselib.c 
e lbitlib.c 
e |corolib.c 
。 ldblib.c 
e liolib.c 

。 |Imathlib.c 
e loslib.c 

e lstrliib.c 
e ltablib.c 
e lutf8lib.c 
。 loadlib.c 
e linit.c 


library, lua.c 
编译 器 : 
library, luac.c 


把 Lua 以 一 个 库 形 式 用 于 你 的 程序 ， 你 需要 知道 如 何 用 你 的 编译 器 创建 库 和 使 用 库 。 比如 ， 
以 动态 加 载 的 C 库 形式 使 用 Lua， 你 需要 了 解 如 何 创建 动态 库 并 让 Lua API 函数 在 动态 库 中 
可 见 一 不 要 将 Lua 库 链 入 每 个 动态 库 。 在 Unix 下 ， 我 们 建议 把 Lua 库 静 态 链 入 宿主 程 

序 ， 然后 将 符号 导出 用 于 动态 链接 ; src/Makefile 就 是 这 样 处 理 Lua 解释 器 的 。 在 
Windows 下 ， 我 们 建议 把 Lua 库 编译 成 一 个 DLL 。 无 论 怎样 ， 编 译 器 luac 都 应 该 静态 链 
接 。 


正如 上 面 所 述 ， 你 可 以 在 构建 Lua 前 编辑 src/luaconf.h 以 定制 一 些 特性 。 


自 Lua 5.2 以 来 的 变更 


这 里 列 出 了 Lua 5.3 引入 的 主要 变更 。 参考 手册 中 列 出 了 不 兼容 的 地 方 。 


主要 变化 


。 整数 (默认 64 位 ) 

。 32 位 整数 的 官方 支持 
。 位 操作 符 

。 基本 的 utf-8 支持 

。 值 的 打包 及 解 包 辑 数 


。 用户 数据 可 以 是 任意 Lua 值 
。 整数 除法 
。 某 些 元 方法 有 了 更 加 灵活 的 规则 


@ ipairs 以 及 表 人 处理 库 都 会 考虑 元 方法 
© string.dump 多 了 裁减 选项 

。 表 处 理 库 考虑 了 元 方法 

。 新 闻 数 table.move 

。 新 函数 string.pack 

。 新 函数 string.unpack 

。 新 加 数 string.packsize 


C API 


。 简化 了 延续 点 API 

e。 lua_gettable 以 及 类 似 图 数 会 返回 结果 的 值 类 型 
e。 lua_dump 增加 了 裁减 选项 

。 新 半数 : lua_ geti 

。 新 函数 : lua_seti 

。 新 函数 : lua_isyieldable 

a 新 画 数 : lua_numbertointeger 


e。 新 函数 : lua_rotate 
。 新 园 数 : lua_stringtonumber 


Lua 独立 解释 器 


。 可 以 做 计算 器 使 用 ; 不 再 需要 前 置 '=' 
。 arg 表 对 所 有 代码 都 可 用 


Lua 参考 手册 5.3 


License 


0SIcertified 


Lua is free software distributed under the terms of the MIT license reproduced below; it may 
be used for any purpose, including commercial purposes, at absolutely no cost without 
having to ask us. The only requirement is that if you do use Lua, then you should give us 
credit by including the appropriate copyright notice somewhere in your product or its 
documentation. For details, see this. 


Copyright © 1994-2015 Lua.org, PUC-Rio. 


Permission is hereby granted, free of charge, to any person obtaining a copy of this 
software and associated documentation files (the "Software"), to deal in the Software 
without restriction, including without limitation the rights to use, copy modify merge， 
publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons 
to whom the Software is furnished to do so, subject to the following conditions: 


The above copyright notice and this permission notice shall be included in all copies or 
substantial portions of the Software. 


THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND， 
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT 
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, 
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 
OTHER DEALINGS IN THE SOFTWARE. 
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